lhk229
65d1489bdd
新增 Anthropic 链路，LLM 请求收口为 LlmRunRequest/LlmApiKind，为未来创建更多字段适配高级功能准备 Reviewed-on: https://git.genarrative.world/git/GenarrativeAI/Genarrative/pulls/70 Co-authored-by: Linghong <ink29535@proton.me> Co-committed-by: Linghong <ink29535@proton.me>
58 lines
3.0 KiB
Markdown
58 lines
3.0 KiB
Markdown
# platform-llm 平台适配 crate
|
|
|
|
日期：`2026-04-21`
|
|
|
|
## 1. crate 职责
|
|
|
|
`platform-llm` 是 Rust 工作区里的大模型平台适配 crate，当前首版已经落地以下能力：
|
|
|
|
1. 统一 Ark / DashScope / Anthropic / 其他兼容网关的文本模型配置结构
|
|
2. 统一 OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages 文本请求、非流式响应与 SSE 流式增量解析
|
|
3. 统一超时、连接失败、上游错误、空响应与重试策略
|
|
4. 为后续 `module-ai`、`module-story`、`module-npc`、`module-custom-world` 提供可直接复用的基础 client
|
|
|
|
## 2. 当前首版边界
|
|
|
|
当前实现只覆盖“文本 run”主链，不提前混入媒体生成和业务编排：
|
|
|
|
1. 对外抽象固定为 `LlmRunRequest` / `LlmRunResponse`，不再保留旧 `LlmTextRequest` / `LlmTextResponse` 类型。
|
|
2. 支持 `OpenAiChat` 和 `OpenAiResponses` 两类 API kind 的 JSON 请求与 SSE 增量响应。
|
|
3. 支持 `Anthropic` API kind 的最小文本 Messages 请求、非流式响应与 SSE 文本增量解析；Anthropic URL 默认在 base URL 后拼 `/v1/messages`，如果 base URL 已以 `/v1` 结尾则只拼 `/messages`。
|
|
4. 当前 run 抽象只收敛通用文本结果、finish reason、response id 和 usage；上下文管理、后台执行、provider 原生工具等高级能力后续再按 capability 显式扩展，不把 Responses 语义硬编码进业务层。
|
|
5. 支持按 provider 打标签，但不把业务 prompt、SSE 转发和模块状态写回本 crate。
|
|
6. `DashScope` 当前只通过“调用方显式提供兼容文本网关 base url”的方式接入，不复用图像 API。
|
|
7. 角色动画、图片、视频、资产轮询仍留在后续 `platform-llm` / `platform-oss` / 业务模块任务里另行实现。
|
|
|
|
## 3. 核心导出
|
|
|
|
首版对外导出以下公共类型：
|
|
|
|
1. `LlmProvider`
|
|
2. `LlmConfig`
|
|
3. `LlmMessageRole`
|
|
4. `LlmMessage`
|
|
5. `LlmRunRequest`
|
|
6. `LlmApiKind`
|
|
7. `LlmStreamDelta`
|
|
8. `LlmRunResponse`
|
|
9. `LlmTokenUsage`
|
|
10. `LlmClient`
|
|
11. `LlmError`
|
|
|
|
## 4. 设计文档
|
|
|
|
## 当前文档入口
|
|
|
|
当前长期工程口径已融合到：
|
|
|
|
1. [../../../docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md](../../../docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md)
|
|
2. [../../../docs/【玩法创作】平台入口与玩法链路-2026-05-15.md](../../../docs/【玩法创作】平台入口与玩法链路-2026-05-15.md)
|
|
3. [../../../docs/【开发运维】本地开发验证与生产运维-2026-05-15.md](../../../docs/【开发运维】本地开发验证与生产运维-2026-05-15.md)
|
|
|
|
旧阶段设计文档不再作为实现依据。
|
|
## 5. 边界约束
|
|
|
|
1. `platform-llm` 只承接模型平台适配，不承接业务模块状态真相与业务规则。
|
|
2. 业务模块只能依赖这里的统一 client / DTO / 错误模型，不能再把上游请求细节散落回各 crate。
|
|
3. `api-server` 后续如果需要做 REST/SSE façade，只允许在协议层调用 `platform-llm`，不能复制一份私有实现。
|