42 lines
2.4 KiB
Markdown
42 lines
2.4 KiB
Markdown
|
# ADR-0011：模型与端点（DeepSeek + 本机配置文件）
|
|||
|
|
|
|||
|
|
- **状态**：已接受
|
|||
|
|
- **日期**：2026-09-28
|
|||
|
|
- **决策人**：技术负责人
|
|||
|
|
- **相关**：任务表 A0（决策 D15）；ADR-0006（引擎运行形态）；ADR-0009（交付形态）
|
|||
|
|
|
|||
|
|
## 背景
|
|||
|
|
|
|||
|
|
引擎要真跑起来就必须调模型。这件事有两个必须现在定的点：用哪个端点，以及密钥放在哪。密钥的处置还牵动一条硬规则——凭据不进模型上下文、不进日志、不进仓库（架构设计 5.1）。
|
|||
|
|
|
|||
|
|
## 选项
|
|||
|
|
|
|||
|
|
| 选项 | 做法 | 代价 | 不选的理由 |
|
|||
|
|
| --- | --- | --- | --- |
|
|||
|
|
| A DeepSeek + 本机配置文件 | 端点用 DeepSeek 的 OpenAI 兼容接口；密钥写在本机配置文件里 | 依赖外部服务可用性 | 选定 |
|
|||
|
|
| B 内网自建网关 | 部署兼容网关，统一收口 | 需要运维与卡资源 | 首版没有现成网关；接口按 OpenAI 兼容写，将来换端点只改配置 |
|
|||
|
|
| C 密钥进环境变量 | 全部走 env | CI 里方便 | 本地开发与桌面端每次都要设环境变量；env 还会被子进程继承，容易外泄 |
|
|||
|
|
|
|||
|
|
## 结论
|
|||
|
|
|
|||
|
|
选 A，并定下配置的三条规则：
|
|||
|
|
|
|||
|
|
| 项 | 结论 |
|
|||
|
|
| --- | --- |
|
|||
|
|
| 端点 | `https://api.deepseek.com/v1`（OpenAI 兼容），模型 `deepseek-chat` |
|
|||
|
|
| 密钥位置 | 本机配置文件 `~/.aps/config.json` 的 `llm.apiKey`；也可用 `APS_CONFIG_FILE` 指定其它路径 |
|
|||
|
|
| 优先级 | 环境变量 > 配置文件 > 默认值（方便 CI 与临时覆盖） |
|
|||
|
|
| 泄露防线 | 密钥不进仓库、不进日志、不进 API 响应；配置对象提供脱敏视图供日志使用 |
|
|||
|
|
| 不可用时 | 模型未配置不阻塞平台启动：默认走假引擎，需要真引擎时报明确错误（A3.3 落地） |
|
|||
|
|
|
|||
|
|
## 影响
|
|||
|
|
|
|||
|
|
- **对代码**：新增 `server/config.ts`；引擎适配层从它取端点与密钥，不自己读环境
|
|||
|
|
- **对任务**：A3.3 子进程接入时把配置注入 Pi 子进程的启动环境；A10.8 发版清单要核对密钥不随包分发
|
|||
|
|
- **对文档**：`.env.example` 改为平台自己的变量；术语表无需改
|
|||
|
|
- **不这么做的后果**：密钥散在代码与 shell 历史里，且子进程继承全部环境变量，泄露面变大
|
|||
|
|
|
|||
|
|
## 遗留
|
|||
|
|
|
|||
|
|
- 生产是否改用内网网关：A10 之前定，届时只改 `llm.baseUrl`
|
|||
|
|
- 是否支持多模型切换（同一个平台配置多个端点）：首版不做，等有第二个使用场景再评估
|