43 lines
3.3 KiB
Markdown
43 lines
3.3 KiB
Markdown
## Why
|
||
|
||
当前 conversion/proxy 层的错误处理和流式透传行为与最新产品决策不一致；路径文档也需要明确职责边界：网关只剥离 `/{protocol}` 前缀，不对剩余路径做版本号归一化，是否包含 `/v1` 由具体协议 adapter 处理。
|
||
|
||
这次调整在应用上线前完成，可以避免错误的路径抽象固化，并为后续新增接口和多模态转换打好边界。
|
||
|
||
## What Changes
|
||
|
||
- 明确网关路径职责：只剥离协议前缀 `/{protocol}`，剩余 path 原样作为客户端协议 nativePath 交给 adapter。
|
||
- 明确不同协议的对外路径由协议自身决定，不做跨协议统一：OpenAI 使用 `/openai/chat/completions`、`/openai/models`、`/openai/embeddings`、`/openai/rerank`；Anthropic 使用 `/anthropic/v1/messages`、`/anthropic/v1/models`、`/anthropic/v1/models/{provider_id}/{model_name}`。
|
||
- 明确 `base_url` 约定不变：OpenAI 配置到版本路径一级（如 `http://xxx.com/v1`），Anthropic 配置到域名级（如 `http://xxx.com`）。
|
||
- adapter 负责识别剥离协议前缀后的协议原生 nativePath，并通过 BuildUrl 产出真实上游路径。
|
||
- 同协议流式无 model 改写时直接透传上游 SSE 字节；需要 model 改写时按 SSE frame 解析和重建，只改写 data JSON 内的 model 字段。
|
||
- 网关层错误使用应用统一错误格式 `{error, code}`；上游已经返回 HTTP 响应时，非 2xx 状态码、headers、body 直接透传，不进入协议转换。
|
||
- 只有 adapter 明确适配的接口才提取 model 并参与统一模型 ID 路由；未知接口不做通用 model 猜测，按无 model 透传处理。
|
||
- 多模态占位保留；本次不实现多模态转换，跨协议检测到 image/audio/video/file 时返回网关层不支持错误。
|
||
- 本次不调整统计口径。
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- 无
|
||
|
||
### Modified Capabilities
|
||
|
||
- `unified-proxy-handler`: 修改 nativePath 语义、同协议流式透传、上游错误透传和未知接口路由规则。
|
||
- `openai-protocol-proxy`: 明确 OpenAI 对外路径和 adapter 接收的 nativePath 形态，并约束流式完成标记和上游错误透传行为。
|
||
- `anthropic-protocol-proxy`: 明确 Anthropic 对外路径保持 `/v1` 层级、adapter 接收 `/v1/...` nativePath、上游 URL 由 `base_url + nativePath`/BuildUrl 组合得到。
|
||
- `error-responses`: 增加网关层统一错误码设计，并明确代理接口中上游错误透传、不做协议错误包装。
|
||
- `conversion-engine`: 约束同协议 Smart Passthrough 的 URL 构建、SSE frame 级 model 改写、adapter 模型提取边界和跨协议多模态暂不支持行为。
|
||
|
||
## Impact
|
||
|
||
- 后端代理入口：`backend/internal/handler/proxy_handler.go`
|
||
- 供应商客户端流式接口：`backend/internal/provider/client.go`
|
||
- 转换引擎和流式转换器：`backend/internal/conversion/engine.go`、`backend/internal/conversion/stream.go`
|
||
- OpenAI/Anthropic adapter：`backend/internal/conversion/openai/*`、`backend/internal/conversion/anthropic/*`
|
||
- 错误处理公共逻辑：`backend/pkg/errors`、handler 错误响应逻辑
|
||
- 测试：conversion 单测、adapter 单测、代理集成测试、E2E conversion 测试
|
||
- 文档：`README.md`、`backend/README.md`、`docs/conversion_design.md`
|
||
- 不引入新依赖，不调整数据库 schema，不调整统计模块
|