江中智能助手 · 架构设计
整体架构
用户在孪生宿主中向助手提问。助手服务按需调用模型、知识和中台能力，整理结果；如果需要三维动作，就把场景指令交回宿主执行。这里先看系统关系，具体组成见核心交付。
可左右滚动查看完整图；点击图可全屏缩放。
部署架构
单机是一台 Windows。大模型网关和 vLLM 是两个进程。调用方只打网关，Qwen 不直接对外。
| 项 | 参数 |
|---|---|
| 机器 | Windows。vLLM 在 WSL2 Ubuntu |
| 网关 | :8080，本机 uvicorn。先验用户 API Key、模型权限和日额度，出站换成内部服务 Key |
| 排队 | 全局并发 5。槽满进等待池，池子 50，从入池起最多等 120 秒 |
| 对话模型 | 调用方写 qwen-9b。网关改成 Qwen3.5-9B-AWQ，转到 127.0.0.1:8001 |
| vLLM | 一次最多 5 路，上下文 16384。短输出可以 5 路一起跑；接近 16k 的长上下文大约只能同时跑 3 路 |
| 账本 | SQLite |
| 门户 | :8080 /login，JWT Cookie。登录、发 Key、改配额 |
| 角色 | 地址 | 凭证 | 职责 |
|---|---|---|---|
| 调用方 | :8080 /v1/* | 用户 API Key | 对话、查账户 |
| 门户网页 | :8080 /login | JWT Cookie | 登录、发 Key、改配额 |
| 网关 | 本机 uvicorn | 验用户 Key，出站换内部 Key | 鉴权、额度、排队、改模型名 |
| vLLM | 127.0.0.1:8001 | 内部服务 Key | 跑 Qwen3.5-9B-AWQ |
请求链路
下面这张图比整体架构多展开一层：助手服务需要模型规划或生成回答时，先经过大模型网关；知识查询走 Dify，中台查询走 MCP。三维动作仍在宿主执行。
可左右滚动查看完整图；点击图可全屏缩放。
前端助手与服务端用 HTTP / SSE 传递问句和结果。服务端调用模型时使用用户 API Key 访问 :8080，网关验证权限和额度后转发到 :8001。知识和中台是按问句需要调用的能力，不是每一轮都依次调用。
关键设计
问句如何选方法并执行
可以按五步理解一次问句：
- 选方法：模型只从本轮已登记的知识、中台和场景方法中选下一步。信息不够就澄清，目录里没有相应动作就说明不支持。
- 校验：服务端核对方法名和参数。参数有误时最多修正两次，修正期间不能换方法；缺设备编号则向用户询问。
- 执行：知识问题查 Dify，业务数据经 MCP 只读查询；场景动作先审查，再作为指令返回宿主。
- 看结果：服务端读取查询结果或场景指令的状态。后一步依赖前一步时，依据实际结果再选下一步，不预先把计划全部执行。
- 回答：步骤完成后依据取得的结果回答。规划失败或下游异常时说明原因；未执行的三维动作不说成已完成。
可左右滚动查看完整图；点击图可全屏缩放。
实现上，route.yaml 负责第一次选择，act.yaml 在看到执行结果后选择下一步；参数校验使用 Zod，场景动作通过审查后才返回。route.yaml 没有给出有效结果时走 error.yaml。问句里已有设备号却被要求澄清时，会再规划一次。
会话记忆
服务端按 conversationId 保存工作上下文、近 6 轮对话和短事实，用于理解「这个设备」等指代。本轮明确说出设备编号时以本轮为准；没有新编号时才参考已保存的上下文。内容超出预算时先丢弃更早的对话轮次。
目录如何交给模型
中台、知识和场景方法目录按内容缓存，随本轮问句交给模型。第一次选择时提供全量目录；需要继续时，只提供原计划涉及的方法，以及已执行和待执行的步骤。系统消息只保留角色规则，目录不塞进系统消息。
什么时候继续下一步
一步就能完成的问句，执行后直接生成回答。必须先看查询结果才能决定后一步时，才进入观察循环。原计划的待执行项只用于提醒模型，不由服务端自动跑完。设备确认不存在时结束相关步骤；如果计划中的三维聚焦被遗漏，只有在符合已有结果时才补充规划与审查。
运行观测
GET /api/traces：进程内最近痕迹，需 Bearer。GET /api/traces/:requestId：按本轮 requestId 查一条。无令牌返回 401。- 重启后内存痕迹清空。逐步耗时在会话夹
actions.log的timing行。 - token 来自模型或 Dify 响应里的 usage 整数。
GET /live、GET /health：无需令牌的基础探活接口，用于确认服务能响应请求；不代表下游依赖已就绪。GET /ready：可接流量，需令牌。失败表示配置或依赖未就绪，不是进程已死。
系统边界
助手只返回声明式 sceneActions，三维方法由宿主执行。中台 SQL 留在 MCP 内，服务端不直接访问。模型调用经单机网关；知识查询另走 Dify。压测条件与运行参数的区别见并发压测。