color_full/docs/adr/0002-ai-api-strategy.md

# ADR-0002: AI 能力通过外部 API 调用实现

> **状态**: 已决议（2026-05-21 修订）  
> **日期**: 2026-05-20  
> **修订**: 2026-05-21  
> **父决策**: ADR-0001（整体技术栈）  
> **决策者**: 架构评审

---

## 上下文

平台需要 AI 能力支撑四大核心模块：配方指标预测、NL 搜索、配方生成/推演、颜色推荐。考虑两种实现路径：

- **方案 A**：自建 Python AI 微服务（FastAPI + 自训练模型）
- **方案 B**：通过外部 AI API 调用实现（LLM API + Prompt Engineering）

---

## 决策

**选择方案 B**：所有 AI 能力通过调用外部 LLM API 实现。

---

## 理由

### 方案 B 优势

| 维度 | 方案 A（自建） | 方案 B（外部 API） |
| :--- | :--- | :--- |
| **开发成本** | 需要 ML 工程师训练模型；数据清洗和标注投入大 | Prompt Engineering 即可；无需 ML 专业背景 |
| **运维成本** | GPU 服务器（至少 1 台 A100）+ 模型部署和监控 | 零运维，按调用量付费 |
| **迭代速度** | 重新训练需数天到数周 | 调整 Prompt 即时生效 |
| **模型能力** | 受限于自有数据量和训练资源 | 持续获得最新大模型能力升级 |
| **部署复杂度** | 增加 1 个微服务 + GPU 依赖 + gRPC | 仅 BFF 层 HTTP 调用 |
| **冷启动** | 模型加载需数分钟 | 即用即走 |

### 化妆品配方场景的特殊适配

配方研发的 AI 需求特点：

1. **推理为主，非训练密集型**：预测肤感/稳定性本质是"基于成分知识的推理"，LLM 的常识推理 + few-shot learning 可以胜任
2. **数据量小**：企业内部配方数据通常是千到万级，不足以训练专用深度学习模型
3. **领域知识密集**：LLM 已具备化学/化妆品基础知识，通过 Prompt 注入成分数据库即可精准推理
4. **需求多变**：配方推演的约束条件千变万化，API 调用的灵活性远胜固定模型

---

## AI Service 架构

```
Route Layer (modules/ai/ai.route.ts)
  │
  ▼
AIService (services/ai/index.ts)
  ├── Provider 抽象层
  │     ├── createOpenAIProvider  (GPT-4o, base: api.openai.com/v1)
  │     └── createDeepSeekProvider (deepseek-chat, base: api.deepseek.com/v1)
  ├── LRUCache (200 条, 带 TTL)
  ├── RateLimiter (10 req/s, token bucket)
  ├── 重试策略 (指数退避, 最多 3 次)
  ├── Fallback → Mock 模式 (AI_MOCK=true 时返回预设数据)
  └── Audit Log → ai_audit_logs 表 (capability, model, tokens, duration)
```

> **修订(2026-05-21)**：AI Service 重构为实例属性管理配置（openaiKey/deepseekKey），不再依赖 `process.env` 直读。Provider 通过 `reload(updates)` 热更新。

---

## AI 能力清单

| Prompt 模板 | 能力 | System Prompt 角色 | 输出格式 |
|-------------|------|--------------------|----------|
| `predictMetricsPrompt` | 预测配方指标 | 资深化妆品配方工程师 | `{sensoryIndex, stabilityScore, costEstimate, confidence, reasoning}` |
| `parseNLQueryPrompt` | 自然语言搜索 | 查询解析器 | `{filters, keywords, vectorQuery}` |
| `generateFormulaPrompt` | 配方推演 | 资深化妆品配方工程师 | `[{name, changes, predictedMetrics, reasoning}]` |
| `recommendColorantsPrompt` | 配色推荐 | 化妆品色彩专家 | `{recommendations: [{colorants, predictedDeltaE, confidence}]}` |
| `extractFormulaPrompt` | 配方文本提取 | 数据结构化提取 | `{ingredients: [{inciName, chineseName, percentage, phase, processNotes}]}` |

---

## 配置管理

| 配置项 | 存储位置 | 说明 |
|--------|----------|------|
| `AI_MOCK` | `runtime/config.json` | Mock 模式开关（开发环境默认 true） |
| `OPENAI_API_KEY` | `runtime/config.json` | 服务器端持久化，客户端不透传 |
| `DEEPSEEK_API_KEY` | `runtime/config.json` | 同上 |
| `OPENAI_BASE_URL` | `runtime/config.json` | 自定义 endpoint（如 API 代理） |
| `DEEPSEEK_BASE_URL` | `runtime/config.json` | 同上 |

> **修订(2026-05-21)**：API Key 从 localStorage 传输改为服务器端文件持久化。前端 SettingsPage 仅显示"已配置/未配置"状态，不展示 Key 内容。

---

## 后果

- 依赖外部 API 服务可用性（OpenAI / DeepSeek），API 不可用时自动降级为 Mock 模式
- AI 响应格式严格约束为 JSON，前端不解析自然语言输出
- 每次 AI 调用记录审计日志，用于成本核算和问题排查
- 新增 AI Provider 只需实现 `AIProvider` 接口（`chat` + `chatStream`）