大肥鱼 API 接口文档
把一个已导入「大肥鱼」人格 / 插件 / 知识库的 AstrBot 实例,包装成稳定可调用的 HTTP API。
业务方只需 GATEWAY_API_KEY + 自己的 user_id;管理面另用 ADMIN_API_KEY,两套凭证物理分离。
Authorization: Bearer <GATEWAY_API_KEY>;
管理接口用 X-Admin-Key: <ADMIN_API_KEY>。用错一律 401。
本页右上角填入 Key 后可直接在线试调,Key 只存于当前页面内存,不写 Cookie、不落日志。
快速开始
最小调用
curl -s http://127.0.0.1:8080/v1/chat \\
-H "Authorization: Bearer $GATEWAY_API_KEY" \\
-H "Content-Type: application/json" \\
-d '{"user_id":"alice","message":"你好","stream":false}'通用约定
| 项目 | 说明 |
|---|---|
| Content-Type | application/json(除 /health 外均需) |
| user_id | 1~128 字符,你系统里的稳定用户 ID。网关用 HMAC 映射为 u_<24hex>,绝不透传原文 |
| stream | true 透传上游 SSE;false 聚合为 {events, session_id} |
| X-Request-ID | 每个响应都带,用于日志追踪(也可由调用方传入) |
| 错误体 | {"detail": "..."},HTTP 状态码语义标准(400/401/404/409/429/503) |
关键响应头
| 响应头 | 含义 |
|---|---|
| X-Quota-Remaining | 当日剩余调用额度 |
| X-Fish-Id | 本次命中的鱼(未传 fish 时为空) |
| X-Memory-Recall | hit=N/scopes=N/ok=N/ms=N/status,仅 recall:true 时出现 |
| X-Memory-Write | status=pending|written|denied|skipped,仅 write:true 时出现 |
业务接口
面向业务程序,只暴露 /health、/v1/chat、会话与通知四类。
健康检查。返回上游地址、人格模式、管理态开关、召回 / 写入配置与配额水位。
响应示例
{"ok":true,"upstream":"http://astrbot:6185","persona_mode":"shared",
"admin_enabled":true,"recall_enabled":false,"write_enabled":false,
"write_mode":"review","write_pending":{"total":0,"pending":0}}发起对话。默认 SSE 流式;stream:false 聚合为非流式结果。支持三种人格模式、按鱼路由、多域召回与分层写入。
请求体
| 字段 | 类型 | 说明 |
|---|---|---|
| user_id | string | 必填,1~128 字符 |
| message | string | array | 必填,字符串或 AstrBot 消息链(图片/语音等富文本) |
| session_id | string | 可选,缺省自动新建;网关按用户加命名空间前缀 |
| stream | bool | 默认 true;false 返回聚合结果 |
| mode | string | shared / tenant / user,默认取服务端配置 |
| config_id | string | 指定 AstrBot 配置档案(tenant 模式) |
| fish | string | 指定鱼(如 chat / work),影响人格、知识库与记忆域 |
| recall | bool | 开启多域召回(主 / 任务 / 用户记忆),默认关闭 |
| write | bool | 开启对话沉淀,默认关闭 |
| write_mode | string | review(默认,先待审)/ auto(直写) |
请求示例
{"user_id":"alice","message":"用一句话介绍你自己","stream":false,"fish":"chat"}非流式响应
{"session_id":"alice_xxx","events":["{\"type\":\"plain\",\"data\":\"...\"}"]}⚠ events 是上游 SSE data: 的原始字符串数组,网关刻意不解析。
真实模型 + 工具链下可能混有 reasoning / tool_call 事件,取正文请优先用 type=complete。
列出某用户的会话。查询参数:user_id(必填)、config_id、fish。
删除指定会话。查询参数:user_id(必填)、config_id、fish。
主动推送消息。需要上游 Key 额外具备 im scope,否则返回上游 403。
{"user_id":"alice","message":"这是一条主动提醒"}管理接口
全部要求 X-Admin-Key,且所有请求(含失败)写入审计流水,只存指纹不存明文凭证。
一屏聚合:health / 策略 / 记忆统计 / 待审 / 审计 / 写入配额 / 限流 / Page API 可达性。
响应字段
| 字段 | 说明 |
|---|---|
| health | 网关 /health 快照 |
| policy | 策略摘要(鱼数量、identity 版本等) |
| memory | 记忆总数、域分布、用户数 |
| pending | 待审统计与分析 |
| audit | 审计条数、成功/失败、动作分布 |
| write_quota | 写入配额与活跃桶 |
| page_api_reachable | LivingMemory Page API 是否可达 |
列出全部鱼及其读 / 写记忆域、绑定的知识库与配置档案。
新增鱼。apply:false 只返回变更 diff,apply:true 才落盘并留 .bak。
业务鱼禁写主记忆、禁声明跨鱼读,服务端全量校验,非法直接 400。
{"fish_id":"study",
"config":{"config_id":"fish_study","kb":["主记忆/常识基座"],
"read":["global","fish:self","user:self"],"write":["fish:self"]},
"apply":false}读取完整分层记忆策略。PUT 同一路径可写回,服务端强校验后落盘并自动备份。
浏览待审记忆。查询参数:status(pending/approved/rejected/all)、fish、pii、q、limit。
批准或拒绝一条待审。approve 走专用通道写入 lm:fish:* 共享域;重复审核返回 409;写入失败保持 pending 可重试。
{"action":"approve","note":"人工确认"}管理请求审计流水。?limit= 控制条数;/v1/admin/audit/export 可直接下载 JSON。
限流 / 日配额 / 写入配额的实时水位与配置,便于排障。
一键只读自检:凭证、上游、Page API、策略、待审队列、配额逐项打勾,不触发任何写操作。
OpenAI 兼容
把 base_url 指向本网关,即可用任何 OpenAI SDK 调用大肥鱼。
鉴权用业务 Key(dfy_...)或根 Key。model 形如 dafeiyu-<fish> 时按该鱼路由。
from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:8080/v1", api_key="dfy_xxx")
resp = client.chat.completions.create(
model="dafeiyu-chat",
messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)支持范围
| 能力 | 状态 | 说明 |
|---|---|---|
| chat.completions | 支持 | stream / 非 stream;system 消息会作为人格前缀注入 |
| models.list | 支持 | 返回 dafeiyu 与每条鱼的 dafeiyu-<fish> |
| temperature / max_tokens | 接收但不生效 | 参数由 AstrBot 侧 Provider 决定,网关不透传 |
| 多轮 messages 历史 | 部分 | 只取最后一条 user;历史由 AstrBot 会话自身维护 |
| embeddings / images / audio | 不支持 | 返回 404 |
⚠ 流式为「先取完整回复再按 48 字分块推送」,SDK 兼容但不是真逐字流;
需要真流式请用原生 /v1/chat。
其余端点
| 方法 | 路径 | 说明 |
|---|---|---|
| PUT | /v1/admin/policy | 校验并保存策略 |
| POST | /v1/admin/policy/diff | 策略改动预览(只读) |
| PUT | /v1/admin/fish/{fish_id} | 修改鱼 |
| DELETE | /v1/admin/fish/{fish_id} | 删除鱼(需 apply:true) |
| PUT | /v1/admin/allowlist | 服务白名单 |
| GET | /v1/admin/pending | 待审列表(简版) |
| GET | /v1/admin/pending/stats | 待审统计 |
| GET | /v1/admin/pending/{item_id} | 单条详情 |
| POST | /v1/admin/batch-review | 批量批准 / 拒绝 |
| GET | /v1/admin/status | 管理态状态 |
| GET | /v1/admin/sessions | 会话与用户视图 |
| GET | /v1/admin/audit/export | 审计导出 |
| POST | /v1/admin/page/{endpoint} | LivingMemory Page API 白名单代理(13 个端点) |
| POST | /v1/admin/migrate-identity | identity 迁移 dry-run |
| GET | /v1/admin/config-profiles | 配置档案候选(鱼表单下拉) |
| GET | /v1/admin/knowledge-bases | 知识库候选(只读 kb.db) |
| GET | /v1/admin/sessions/list | 按记忆域聚合的活跃会话 |
| GET | /v1/models | OpenAI 兼容:模型列表 |
| POST | /v1/chat/completions | OpenAI 兼容:对话补全 |
| GET | /v1/admin/keys | API Key 列表(含用量) |
| POST | /v1/admin/keys | 签发 Key(明文只返回一次) |
| PATCH | /v1/admin/keys/{id} | 修改 Key 绑定与限额 |
| POST | /v1/admin/keys/{id}/rotate | 轮换(旧 Key 立即失效) |
| POST | /v1/admin/keys/{id}/revoke | 吊销 |
| GET | /v1/admin/usage | 调用量 / 错误率 / 平均耗时 |
| GET | /v1/admin/providers | AI 网关:Provider 列表(凭证打码) |
| PATCH | /v1/admin/providers/{id}/enabled | 启用 / 停用(实时生效) |
| POST | /v1/admin/providers/{id}/test | 连通性测试(需 model) |
| POST | /v1/admin/providers | 接入新 Provider(需 key) |
| DELETE | /v1/admin/providers/{id} | 删除(需 confirm:true) |
错误码
| 状态码 | 含义 | 处理建议 |
|---|---|---|
| 400 | 参数非法 / 策略校验失败 | 看 detail,修正后重试;不要盲目重试 |
| 401 | 凭证缺失或错误 | 检查用的是业务 Key 还是管理 Key |
| 404 | 路径不存在 / 非白名单 | 核对路径拼写与方法 |
| 409 | 重复审核 / 状态冲突 | 刷新列表后再操作 |
| 429 | 触发限流或日配额 | 退避重试,或调高配额 |
| 503 | 管理态未配置 / 上游不可用 | 检查 ADMIN_API_KEY 与上游容器 |