5.3 KiB
5.3 KiB
能力路由规则文档 (CAPABILITY_ROUTING.md)
谁敢改这些文件的任何一行前，必须通读本文档。 更新日期: 2026-07-28 | 维护人: Senior Developer
一、核心原则
✅ 所有路由路径最终汇聚到 capability_registry.resolve_auto_model
✅ 文本/推理/视觉/工具能力必须指向有 "text" capabilities 的模型
✅ 图像/视频/语音能力在有明确意图时才触发（不会误判普通对话）
✅ 新增能力类型必须在 CAPABILITY_TYPES 注册，否则路由不可见
二、路由路径 (谁在什么时候决定用哪个模型)
| 入口 | 文件 | 行号 | 决策逻辑 | 出错表现 |
|---|---|---|---|---|
| 前台用户对话 | chat_service.py | 2730 | intent = detect_media_intent(req.content) → 媒体意图 → 图像/视频/语音模型 |
普通对话被误判走图像 |
| 前台 Auto 模式 | chat_service.py | 2750 | ai_model = resolved or resolve_auto_model("text", db) → 无意图时回退文本 |
无法对话 |
| defensive guard | chat_service.py | 2898-2905 | 模型有 image/video 能力但用户无媒体意图 → 强制 resolve_auto_model("text") | 被 guard 修复后走 text |
| 后台 "按能力默认模型" 页 | admin/models.py | 495 | get_capability_defaults(db) → 读 site_settings JSON → 填到 UI dropdown |
页面不显示默认模型 |
| 后台 模型测试 (connect) | admin/models.py | 870-954 | _detect_model_type(capabilities) → 按 cap 分类测试 |
测试走错端点 |
| 关键词检测 | chat_media.py | 97-157 | detect_media_intent(text) → 基于关键词白名单 |
词库不全导致误判/漏判 |
| 模糊创作意图 | chat_media.py | 200-240 | detect_ambiguous_creative_intent(text) → 无媒体词但有创作动词 |
提示不准确 |
| 前端能力下拉 | admin/Models.tsx | 534-559 | lockedCapDefaults → 动态锁定 is_default=true 模型到 text/thinking |
显示错误的锁定模型 |
| 前端模型下拉 (前台) | ChatPage.tsx | 1486-1498 | model.capabilities → cap badge 显示 |
多显示/少显示 badge |
| 模型变更 API | admin/models.py | 670-672 | is_default 切换 |
旧默认模型未解除锁定 |
三、能力定义 (唯一真相源)
# capability_registry.py lines 17-35
CAPABILITY_TYPES = [
{"id": "text", "label": "文本对话", "desc": "文本生成与多轮对话"},
{"id": "thinking", "label": "推理思考", "desc": "深度推理 / 思维链"},
{"id": "vision", "label": "视觉理解", "desc": "图片 / 多模态理解"},
{"id": "tool", "label": "工具调用", "desc": "Function Calling"},
{"id": "image", "label": "图像生成", "desc": "文生图"},
{"id": "video", "label": "视频生成", "desc": "文生视频"},
{"id": "audio", "label": "语音合成", "desc": "TTS 文字转语音"},
{"id": "asr", "label": "语音识别", "desc": "ASR 语音转文字"},
{"id": "ocr", "label": "OCR识别", "desc": "图片文字识别"},
{"id": "embedding", "label": "嵌入向量", "desc": "文本向量化"},
{"id": "rerank", "label": "重排序", "desc": "语义重排"},
]
TEXT_FAMILY = {"text", "thinking", "vision", "tool"} # 回退到 is_default 模型
四、媒体意图关键词白名单 (chat_media.py)
图像触发词 (image_kw)
图片/图像/插画/海报/照片/头像/壁纸/漫画/表情包/logo/图标
画一张/画张/画一只/画只/画个/画幅
生成图片/生成一张/生成一幅/生成图/图像生成
帮我画/给我画/请画/绘制/作画/ai绘画/ai画图
画画/画一下/画出来/生成个图
帮我生成图片/帮我生成图像/给我生成图片
来一张图片/画一张图片/画一幅/画一副
视频触发词 (video_kw)
视频/短片/影片/动画视频
做个视频/生成视频/视频生成
生成一个视频/制作一个视频/帮我做视频/制作视频
生成短片/做短片/制作短片/一段短片
一段视频/来段视频/拍个视频/做段视频
语音触发词 (audio_kw)
语音/配音/朗读/播报/念一段/有声/tts/音频/生成语音
读一下/念一下/语音合成
不触发的语句
疑问句（？结尾或含 吗/呢/怎么/如何/能否/可以吗/会不会）
已有明确文本形式（文案/文章/诗/代码/总结/翻译/报告/PPT）
五、修改检查清单
每次修改上述任何文件的代码，必须：
- 重新跑
tests/test_regression_r4.py(30 条用例，含 detect_media_intent 19 个边界) - 调用
GET /app/api/health/bug-audit确认 healthy=true (16 项检查) - 手动测试一条普通文字（如"你好"）→ 必须走 text 模型
- 手动测试一条图像指令（如"画一只猫"）→ 必须走 image 模型
- 修改关键词白名单 → 同步更新本文档 §四
- 新增能力类型 → 同步更新本文档 §三 + capability_registry.py CAPABILITY_TYPES
六、回归防护网
| 层级 | 机制 | 触发时机 |
|---|---|---|
| pre-commit | bug-audit API + Python syntax | git commit |
| pre-push | bug-audit + pytest + vitest | git push |
| unit test | test_regression_r4.py (30 cases) | pytest |
| runtime guard | chat_service.py defensive guard | 每次用户请求 |
| bug-audit API | /api/health/bug-audit (16 checks) | 手动/CI |