Genarrative/docs/technical/API_SERVER_PLATFORM_LLM_PROXY_DESIGN_2026-04-21.md

api-server 接入 platform-llm 最小代理设计（2026-04-21）

1. 目标

在 platform-llm 已落成真实 Rust crate 后，api-server 需要尽快拥有一条可正式消费的平台接线面，避免平台层只停留在“可编译但未接入”状态。

本次目标只做最小闭环：

1. 在 api-server 配置层补齐 LLM 文本网关环境变量
2. 在 AppState 注入 platform-llm::LlmClient
3. 提供 /api/llm/chat/completions 非流式兼容代理
4. 保持与旧 Node 路由的鉴权位置和基本请求形态一致

2. 本次范围

2.1 本次实现

1. AppConfig 新增 LLM provider / base url / api key / model / timeout / retry 配置
2. AppState 初始化 LlmClient
3. 新增 shared-contracts::llm
4. 新增 api-server/src/llm.rs
5. 路由挂载到 /api/llm/chat/completions

2.2 本次不实现

1. 不实现 SSE 流式透传
2. 不实现通用原样 body 转发
3. 不实现媒体模型路由
4. 不把 module-ai 编排接进来

3. 兼容口径

保持与旧 Node POST /api/llm/chat/completions 一致的基本语义：

1. 需要登录态
2. 接收 model? + stream + messages[]
3. 当前 stream=true 明确返回 501，避免伪装支持
4. 非流式返回统一后的文本结果，而不是原样上游 JSON

4. 返回结构

Rust 首版返回：

1. id
2. model
3. content
4. finishReason

原因：

1. 当前 Rust 平台层已经把上游 choices[0].message.content 归一完成
2. api-server 首版先保持稳定、可消费的文本结果接口
3. 真正需要 OpenAI 完全兼容响应体时，再单独补“原样代理模式”

5. 验收

1. api-server 能在配置合法时成功构建 AppState
2. /api/llm/chat/completions 能通过测试打到 mock 上游
3. stream=true 返回明确错误
4. crate 级 check/test 通过

6. 环境变量与默认值

api-server 首版按以下优先级解析 LLM 配置，保证兼容仓库现有 .env 口径：

1. provider：GENARRATIVE_LLM_PROVIDER -> LLM_PROVIDER
2. base url：GENARRATIVE_LLM_BASE_URL -> LLM_BASE_URL
3. api key：GENARRATIVE_LLM_API_KEY -> LLM_API_KEY -> ARK_API_KEY
4. model：GENARRATIVE_LLM_MODEL -> LLM_MODEL -> VITE_LLM_MODEL
5. timeout：GENARRATIVE_LLM_REQUEST_TIMEOUT_MS -> LLM_REQUEST_TIMEOUT_MS
6. max retries：GENARRATIVE_LLM_MAX_RETRIES -> LLM_MAX_RETRIES
7. retry backoff：GENARRATIVE_LLM_RETRY_BACKOFF_MS -> LLM_RETRY_BACKOFF_MS

默认值统一对齐 platform-llm：

1. provider：ark
2. base url：https://ark.cn-beijing.volces.com/api/v3
3. model：doubao-1-5-pro-32k-character-250715
4. request timeout：30000
5. max retries：1
6. retry backoff：500

补充约束：

1. 如果 api key 未配置，api-server 允许继续启动，但 /api/llm/chat/completions 返回 503
2. 如果 provider 字符串非法，回退到默认 ark，避免因为环境变量拼写问题阻断开发态服务

7. 错误映射

platform-llm 到 HTTP 的错误映射固定如下：

1. InvalidRequest -> 400 BAD_REQUEST
2. InvalidConfig -> 503 SERVICE_UNAVAILABLE
3. Timeout / Connectivity / Transport / Deserialize / EmptyResponse / StreamUnavailable -> 502 BAD_GATEWAY
4. Upstream(status=429) -> 429 TOO_MANY_REQUESTS
5. 其他 Upstream -> 502 BAD_GATEWAY
6. stream=true 首版直接返回 501 NOT_IMPLEMENTED