Osmanthe 助理：用自然语言问、查、做仪表盘
2026-10-15 · 返回文档目录
一、它能做什么
每个页面右下角都有「✦ 助理」按钮，点开后直接用中文说你想做什么。它是一个全能助理：
- 讲怎么用产品：比如「怎么一步一步创建仪表盘？」「怎么上传 CSV？」「OpenTelemetry 怎么把日志发进来？」，按页面上真实的按钮名一步步说明。
- 帮你写查询：说「我要看支付服务最近一小时的超时错误」，它写出 SPL，先在你的数据上跑一遍确认能用，再交给你。回答里的查询下面有「在搜索页运行」和「复制」按钮。
- 自己查数据回答问题：问「最近 24 小时哪个服务错误最多？」，它会先看你有哪些字段，再运行查询，根据结果回答，并告诉你用的是哪条查询。
- 按指令保存仪表盘：说「帮我做一个错误监控仪表盘」，它会设计几个面板（错误数、错误趋势、错误类型排行等），逐个验证查询后加到「仪表盘」页。
- 一键自动生成仪表盘：在「仪表盘」页点「✦ 自动生成仪表盘」（仪表盘为空时页面中间也有这个按钮，助理欢迎语里也有），不用打字。助理先看这个租户有哪些字段，自己挑 4 到 6 个最有用的指标，验证查询有结果后直接加上，完成后简短说明加了什么。可以反复点，已有的面板不会重复加。
回答上方的「助理执行了 N 步」可以展开，看它跑了哪些查询、每次返回多少行，每条查询都能点「打开」到搜索页看完整结果。
二、怎么用
- 在页面上方填好 API Key（助理只能看这个 Key 对应租户的数据）。
- 点右下角「✦ 助理」，可以点一个示例问题，或者直接输入，回车发送（Shift+回车换行）。
- 它会记住这段对话的上下文，可以接着问「换成按小时看趋势」「再加一个 P95 延迟的面板」。
- 助理面板打开后贴在页面右边，页面会自动变窄让出位置，两边都能同时用，不再挡住页面内容。拖动面板左边缘可以调宽窄（最宽半个屏幕），这台设备会记住。点 ✕ 收起，对话会保留，再点「✦ 助理」接着聊。
- 手机上助理从下方弹出，只占下半屏，上半屏的页面照常能看、能滚动；点「放大」占满大部分屏幕，再点「缩小」还原。
- 「新对话」清空重来。对话在服务器上保留 2 小时，刷新页面后从新对话开始。
它知道你当前在哪个页面、搜索框里的查询、选的时间范围、仪表盘上已有哪些面板，所以可以说「把我现在这个查询改成按服务分组」。
可以这样问
三、安全边界
- 只读：助理只能搜索、看字段和查找表，不能写日志、不能上传、不能改查找表（含 outputlookup 的查询会被拒绝，需要你自己点「搜索」执行）。
- 租户隔离：所有查询都用你填的 API Key 执行，对话也绑定这个租户，换成别的租户的 Key 不能接着用这段对话。
- 用户权限：用账号登录时，助理的每个工具都按这个用户能看的 index 执行，网关在底层统一过滤，助理写什么查询都越不过去。每次提问时网关也会告诉模型「这个用户能看哪些 index」，所以它不会去猜别的 index。对话绑定到这个用户，同租户的其他人或 API Key 接不上这段对话。
- 模型和 Key 由管理员设置：普通用户在「设置」里只能看到现在用的是哪个模型，不能改。
- 仪表盘面板只接受统计类查询（stats、timechart、chart、top 等），每个面板保存前网关都会先检查查询能不能执行。仪表盘和以前一样保存在这台设备的浏览器里。
- 查询结果会发给你选的模型服务（Mistral AI 或 Claude API）用来生成回答：每次最多约 200 行统计结果或 50 条日志，长字段会截断。含敏感数据的租户上线前要确认这一点可以接受。
四、开启：选模型服务、配置 API Key
助理可以用两家的语言模型，首选 Mistral AI：
| 模型服务 | 默认模型 | Key 在哪创建 |
|---|---|---|
| Mistral AI（推荐，默认） | mistral-large-latest | console.mistral.ai 的 API Keys 页面 |
| Claude（Anthropic） | claude-opus-5-5 | console.anthropic.com 的 API Keys 页面，形如 sk-ant-… |
没配置任何 Key 时按钮照常显示，但发消息会提示「还没有配置语言模型的 API Key」。有两种配法，任选一种：
方法一：在页面里选、在页面里填（推荐，不用重启）
- 在页面上方填好你的 API Key（模型服务和 Key 都按租户保存，填哪个租户的就给哪个租户配）。
- 点右下角「✦ 助理」，再点助理面板右上角的「设置」。还没配置时会自动打开。
- 在「语言模型」下拉框里选 Mistral AI 或 Claude，默认是 Mistral AI。
- 把这家的 API Key 粘贴进去，点「保存」。网关会先向这家的 API 验证，Key 无效时直接提示、不保存；通过后显示「已保存，验证通过」，助理马上改用这家。
- 两家都有 Key 时，在下拉框里选另一家，点「改用 …」就能切换。切换后下一条消息开始新对话（两家的对话记录格式不通用）。
谁来回答：先看这个租户在「设置」里选的；没选过就用网关配置的首选（默认 Mistral AI）；首选没有 Key 时自动用另一家有 Key 的。设置面板和助理欢迎语里都会写明现在用的是哪家、哪个模型。
Mistral 的免费套餐（Experiment）没有 mistral-large，medium 和 small 也调不了。遇到这种 Key，网关会按 mistral-large → mistral-medium → mistral-small → ministral-14b → ministral-8b 的顺序自动换成套餐里能用的最好的模型，并记住它（网关重启后重新找一次）。免费套餐实际用的是 ministral-14b，回答质量比 large 差，复杂的查询可能写不对；要更好的效果，在 console.mistral.ai 升级套餐。一个都用不了时，助理会提示套餐不够，而不是说 Key 无效。
说明：
- Key 保存在网关的 assistant-keys 卷里，每个租户每家一个文件，只有网关进程能读；页面和接口之后只显示末 4 位。
- 只对这个租户生效，这个租户的人都会共用它，费用记在填进去的那个 Key 的账户上。
- 租户自己的 Key 优先于下面的网关默认 Key。在「设置」里点「删除这个租户的 Key」就会改回默认 Key（如果有）。
- 接口（都要带登录令牌 X-API-Key，改设置要管理员）：
GET /api/v1/assistant：现在用哪家（provider、model），以及每家有没有网关 Key、租户 Key（providers）。PUT /api/v1/assistant/key，正文{"provider":"mistral","api_key":"…"}，provider 可选 mistral 或 anthropic，不写时按 anthropic（兼容旧版）；保存后改用这家。DELETE /api/v1/assistant/key?provider=mistral：删除这家的租户 Key。PUT /api/v1/assistant/provider，正文{"provider":"anthropic"}：改用这家，这家必须已经有 Key。
方法二：管理员设置网关默认 Key
给网关设置环境变量 MISTRAL_API_KEY（以及/或者 ANTHROPIC_API_KEY），所有没有自己 Key 的租户都用它。用仓库的 docker compose 时，在 deploy/.env（已加入 .gitignore，不会提交）里写：
MISTRAL_API_KEY=... ANTHROPIC_API_KEY=sk-ant-...
然后重建网关：
docker compose -p coding -f deploy/docker-compose.yml up -d --build gateway
可选配置（配置文件 [assistant] 段）：
| 配置 | 默认 | 说明 |
|---|---|---|
| provider | mistral | 租户没选过时首选哪家：mistral 或 anthropic；也可用 OSMANTHE_ASSISTANT_PROVIDER |
| mistral_model | mistral-large-latest | Mistral 模型，比如 mistral-medium-latest；也可用 OSMANTHE_ASSISTANT_MISTRAL_MODEL |
| mistral_base_url | https://api.mistral.ai | 走代理时改这里，或用 MISTRAL_BASE_URL |
| model | claude-opus-5-5 | Claude 模型；也可用环境变量 OSMANTHE_ASSISTANT_MODEL |
| effort | medium | 只对 Claude：low / medium / high / xhigh / max，越高回答越仔细，越慢越贵 |
| fallback | true | 只对 Claude：请求被安全分类器拒绝时，由 API 自动换 Anthropic 推荐的模型重试 |
| base_url | https://api.anthropic.com | Claude 走代理时改这里，或用 ANTHROPIC_BASE_URL |
| max_steps | 12 | 一条消息最多调用几次模型（含查数据的轮次） |
| timeout_secs | 180 | 单次调用超时 |
| keys_dir | assistant-keys | 租户在页面上填的 Key 和选择存放目录；镜像里是 /var/lib/osmanthe/assistant-keys，也可用 OSMANTHE_ASSISTANT_KEYS_DIR |
费用估算
一个需要查两三次数据的问题通常是几万输入 token、一两千输出 token。Claude Opus 5.5 价格是输入每百万 token 4 美元、输出 20 美元，系统说明和工具定义约 5 千 token 会被缓存，大约几美分到一毛多美元。Mistral 按它官网的当前价格算，这里没有实测；Mistral 这边没有用提示缓存，每一步都会重新发送整段对话。上线前建议加用量上限和按租户限流（见问题清单 P 项）。
五、还没做的
- 回答是整段返回的，不是边想边显示；复杂问题要等十几秒到一分钟。
- 对话只存在网关内存里，网关重启就没了；也没有历史记录列表。
- 还不能删除或修改已有面板，只能添加（删除在仪表盘页点 ✕）。
- 没有按租户的用量统计和限额。