susi_python新手功能清单:聊天、登录、记忆、定位6大核心功能一次讲透
susi_python新手功能清单:聊天、登录、记忆、定位6大核心功能一次讲透
susi_python 是开源 AI 智能助手 SUSI.AI 的官方 Python Wrapper(API 封装库),让你用几行 Python 代码就能让程序拥有 AI 聊天机器人能力:与 SUSI 对话、账号登录、回忆历史记忆、识别地理位置。这篇面向新手的功能清单将 susi_python 的 6 大核心功能一次讲透,并附上完整功能速查表,帮助你几分钟内搭出自己的 AI 对话应用。
🚀 快速上手:3步装好 susi_python
susi_python 依赖很轻(requirements.txt 中仅需 requests、youtube-dl、geocoder 三个库),克隆源码后安装即可:
git clone https://gitcode.com/gh_mirrors/su/susi_python
cd susi_python
pip install -r requirements.txt
pip install .
装好后发一句"hello"试试:
import susi_python as susi
reply = susi.ask("hello")
print(reply.get("answer"))
能收到回复,说明你的 AI 聊天通道已经打通 ✅。官方还附了完整的可运行示例 sample.py,以及一个最小的冒烟测试 tests/test_simple.py。
💬 功能1:AI 聊天 —— 一行代码完成对话
所有对外暴露的函数都集中在 susi_python/init.py,其中最核心的就是 ask():
reply = susi.ask("Tell me a joke")
if "answer" in reply:
print("SUSI:", reply["answer"])
ask() 内部会调用 query() 发起请求,并自动带上时区偏移(timezoneOffset)和设备类型(device_type=Smart Speaker)参数,无需你手动拼任何 URL。它的返回是一个结构化的 dict,文本答案在 answer 键里。
🔐 功能2:账号登录与注册 —— 开启个性化体验
匿名使用也能聊天,但登录后 SUSI 才能记住"你是谁"。认证相关函数定义在 main.py:
# 注册
susi.sign_up("you@example.com", "your_password")
# 登录(获取 access_token)
susi.sign_in("you@example.com", "your_password")
# 忘记密码
susi.forgot_password("you@example.com")
三个关键细节:
- 登录成功后会拿到
access_token,之后的每次ask()都会自动携带,实现个性化回答(见 query()); sign_in()支持第三个参数room_name,传入后会调用 add_device(),自动把当前设备的 MAC 地址、所在房间和经纬度注册为一台智能音箱设备;- 登录态是
ask()和记忆功能生效的前提。
🧠 功能3:记忆回忆 —— 找回历史对话
SUSI 会保存你和它聊过的内容,随时可以取回:
history = susi.get_previous_responses()
该函数(get_previous_responses())会从服务端的 /susi/memory.json 接口拉取历史对话记录并解析为对象。做续聊提醒、会话回放、个人助理日志时,这一招非常实用。
📍 功能4:地理位置感知 —— 让答案"本地化"
想让 SUSI 回答"今天天气如何""附近有什么"这类问题时,先告诉它你在哪里:
susi.update_location(39.9042, 116.4074, "China", "CN")
reply = susi.ask("What's the weather today?")
update_location()(main.py)接收四个参数:纬度、经度、国家名、国家代码。设置之后,每次 query() 都会自动附加这些位置参数(main.py),SUSI 就能给出本地化的回答。
🏠 功能5:本地部署 —— 私有化的 AI,数据不出门
susi_python 默认连接官方云端,但也完全支持本地 susi_server,而且非常"聪明":
- 模块导入时会自动执行 check_local_server(),探测
http://localhost:4000:本地有服务就用本地,没有就用云端,全程无需配置; - 也可以在代码里显式指定端点:
susi.use_api_endpoint("http://localhost:4000")
配合本地部署,你的 AI 助手可以完全离线运行——正如官方 README 所说:"hosted locally for maximum privacy. No cloud needed"(见 README.md)。
🎨 功能6:富媒体响应 —— 不止于文字
SUSI 的回答远不止文字。ask() 返回的 dict 可能包含这些键,解析逻辑在 generate_result() 中:
| 返回键 | 含义 | 典型场景 |
|---|---|---|
answer |
文本回答 | 普通问答 |
table |
表格(表头+数据行) | 查询类技能,如汇率、赛程 |
map |
地图(自带 OpenStreetMap 链接) | 定位查询 |
rss |
新闻条目列表 | 新闻播报 |
identifier |
音频/视频标识(视频带 ytd- 前缀) |
音乐、视频播放 |
volume / media_action |
音量与媒体控制 | 暂停/恢复/下一首/随机播放 |
language |
语言切换 | 切换回答语言 |
planned_actions |
定时任务(带延迟与日期) | "明天7点提醒我" |
例如表格结果会被封装成 Table 对象,地图则封装成带 openStreetMapLink 的 Map 对象,直接取链接即可展示。完整的多类型处理写法可以参考 sample.py 中的响应处理循环。
📋 6大核心功能速查表
| # | 功能 | 调用方式 | 一句话说明 |
|---|---|---|---|
| 1 | AI 聊天 | susi.ask("问题") |
一行代码与 SUSI 对话,自动携带时区与设备信息 |
| 2 | 登录注册 | susi.sign_in() / susi.sign_up() |
获取 access_token,解锁个性化与设备注册 |
| 3 | 记忆回忆 | susi.get_previous_responses() |
拉取历史对话,做续聊与日志 |
| 4 | 位置感知 | susi.update_location(lat, lon, 国家名, 代码) |
让天气、新闻等回答本地化 |
| 5 | 本地部署 | susi.use_api_endpoint(url) |
连接本地 susi_server,完全离线、数据不出门 |
| 6 | 富媒体响应 | 解析 ask() 返回值 |
表格、地图、RSS、音视频、媒体控制一次搞定 |
🎯 写在最后
susi_python 目前处于 Beta 阶段(见 setup.py),核心聊天与认证功能已经可用。按照官方路线图(README.md 的 Roadmap 章节),Maps、Charts 等更多 SUSI.AI API 查询支持正在陆续实现中——现在上手,正好赶上它的成长期。
从 pip install . 到 susi.ask("hello"),你离一个属于自己的 AI 聊天机器人只差几分钟。💬