fix: 完善转换代理行为
This commit is contained in:
@@ -1,2 +0,0 @@
|
||||
schema: spec-driven
|
||||
created: 2026-04-25
|
||||
@@ -1,100 +0,0 @@
|
||||
## Context
|
||||
|
||||
当前后端代理入口采用 `/{protocol}/*path`，`ProxyHandler` 将剥离协议前缀后的 path 作为 `nativePath` 传入 adapter。这个模型本身是合理的：OpenAI adapter 应接收 `/chat/completions`，Anthropic adapter 应接收 `/v1/messages`。需要修正的是文档中曾把版本路径抽象为网关统一规则，但实际上版本路径是否存在属于协议原生路径的一部分，应由协议 adapter 识别和映射。
|
||||
|
||||
流式链路当前由 `ProviderClient.SendStream` 按 `\n\n` 拆分 SSE 事件，并把 `data: [DONE]` 转成 Done 信号。这个设计适合跨协议 decoder，但不适合同协议 raw passthrough：透传路径会丢失 SSE frame 结尾空行，Smart Passthrough 也无法对 `data: {...}` 中的 JSON 顶层 model 做可靠改写。
|
||||
|
||||
错误处理目前混合了协议错误、应用错误和上游错误。新的产品决策是：网关层错误使用应用统一 `{error, code}` 格式；只要上游已经返回 HTTP 响应，即使是非 2xx，也保持透明代理语义，直接透传上游 status、headers、body。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- 明确网关只剥离协议前缀，不对剩余 nativePath 做版本号归一化。
|
||||
- 明确不同协议的 nativePath 形态由协议自身决定：OpenAI 为 `/chat/completions`，Anthropic 为 `/v1/messages`。
|
||||
- 保持现有 `base_url` 约定：OpenAI 配置到版本路径一级，Anthropic 配置到域名级。
|
||||
- 由 adapter 负责识别协议原生 nativePath，并通过 BuildUrl 产出真实上游路径。
|
||||
- 同协议无 model 改写的流式请求保持 raw SSE 字节透传。
|
||||
- 同协议需要 model 改写的流式请求按 SSE frame 解析，只改写 `data` JSON 中的 model 字段，再重建 SSE frame。
|
||||
- 网关层错误统一使用应用错误格式；上游非 2xx 响应透明透传。
|
||||
- 只有 adapter 明确适配的接口才提取 model；未知接口不做通用 model 猜测。
|
||||
- 跨协议遇到多模态占位内容时明确返回不支持错误，避免静默丢内容。
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- 不统一不同协议是否使用 `/v1` 版本路径。
|
||||
- 不调整 OpenAI/Anthropic `base_url` 配置约定。
|
||||
- 不调整统计口径和统计数据模型。
|
||||
- 不实现多模态正式转换。
|
||||
- 不引入新依赖。
|
||||
|
||||
## Decisions
|
||||
|
||||
### Decision 1: nativePath 保持协议原生路径
|
||||
|
||||
外部请求 `/{protocol}/{path}` 只剥离协议前缀，剩余 path 原样作为 client protocol 的 nativePath。OpenAI 请求 `/openai/chat/completions` 进入 OpenAI adapter 时为 `/chat/completions`；Anthropic 请求 `/anthropic/v1/messages` 进入 Anthropic adapter 时为 `/v1/messages`。
|
||||
|
||||
替代方案是由网关统一添加或移除 `/v1`。该方案会把版本路径从协议知识错误提升为网关通用规则，导致 Anthropic 和 OpenAI 的 base_url 约定被混淆。
|
||||
|
||||
### Decision 2: 对外路径由协议 adapter 的 nativePath 决定
|
||||
|
||||
网关不提供跨协议统一路径规范。OpenAI 对外路径不带 `/v1`，因为 OpenAI provider 的 `base_url` 已配置到版本路径一级；Anthropic 对外路径保留 `/v1`，因为 Anthropic 协议原生路径包含版本段且 `base_url` 配置到域名级。
|
||||
|
||||
替代方案是把所有协议对外路径都改成不带 `/v1` 或都带 `/v1`。该方案不符合各协议原生路径，也会让 adapter 的 `DetectInterfaceType` 失去协议边界。
|
||||
|
||||
### Decision 3: 上游路径由 adapter.BuildUrl 产生
|
||||
|
||||
无论同协议透传、Smart Passthrough 还是跨协议转换，出站 URL 都使用 `provider.BaseURL + providerAdapter.BuildUrl(nativePath, interfaceType)`。OpenAI adapter 对 `/chat/completions` 返回 `/chat/completions`，配合 `base_url=http://xxx.com/v1` 得到 `http://xxx.com/v1/chat/completions`。Anthropic adapter 对 `/v1/messages` 返回 `/v1/messages`，配合 `base_url=http://xxx.com` 得到 `http://xxx.com/v1/messages`。
|
||||
|
||||
替代方案是在 engine 中直接拼接 `provider.BaseURL + nativePath`。该方案当前对部分协议可工作，但绕过了 adapter 的 URL 映射职责，不利于后续协议扩展和特殊路径映射。
|
||||
|
||||
### Decision 4: 同协议流式分 raw passthrough 和 smart passthrough 两条路径
|
||||
|
||||
当 clientProtocol 等于 providerProtocol 且不需要响应 model 改写时，handler/provider client 应直接将上游响应 body 的 SSE 字节写回客户端，不进入 `StreamConverter` 事件拆分链路。
|
||||
|
||||
当需要响应 model 改写时，保留 SSE frame 边界，解析每个 SSE frame 的 `data` 行：`[DONE]` 原样输出；JSON payload 调用 adapter 的响应 model 改写逻辑后重新写为 SSE frame；解析失败则按宽容策略输出原 frame。
|
||||
|
||||
替代方案是继续让 `ProviderClient.SendStream` 只暴露去掉 `\n\n` 的 rawEvent。该方案无法满足 raw passthrough 的字节语义，也无法可靠输出 `[DONE]`。
|
||||
|
||||
### Decision 5: 网关层错误与上游错误分离
|
||||
|
||||
网关层错误包括路由失败、请求 JSON 错误、转换失败、上游连接失败、跨协议暂不支持能力等，统一返回 `{error, code}`。上游错误指已经收到上游 HTTP 响应的情况，非 2xx 响应不进入 conversion，直接透传 status、过滤后的 headers 和 body。
|
||||
|
||||
替代方案是把所有代理错误都编码为客户端协议错误格式。该方案会隐藏上游原始错误，也与管理接口统一错误格式不一致。
|
||||
|
||||
### Decision 6: adapter 明确声明可提取 model 的接口边界
|
||||
|
||||
Chat、Embeddings、Rerank 等已适配接口由 adapter 的 `ExtractModelName` 明确解析 model。未知接口即使 body 中存在顶层 `model`，也不做假设性提取，按无 model 透传处理。
|
||||
|
||||
替代方案是在 handler 中统一尝试解析顶层 model。该方案会误判未来协议特有接口的模型字段语义，破坏 adapter 对协议知识的封装。
|
||||
|
||||
### Decision 7: 多模态占位保留但跨协议拒绝
|
||||
|
||||
Canonical 中现有 image/audio/video/file 占位保留，后续多模态实现可继续扩展。同协议 Smart Passthrough 保留请求 JSON 语义，不检查多模态。跨协议完整转换检测到 image/audio/video/file 时返回 `UNSUPPORTED_MULTIMODAL` 网关错误。
|
||||
|
||||
替代方案是继续编码空占位或静默丢弃。该方案会制造数据丢失，调用方难以诊断。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Risk] 对外路径由协议决定，调用方需要分别记住 OpenAI 和 Anthropic 的路径形态。→ Mitigation: README、backend README 和设计文档明确列出每个协议的路径和 base_url 约定。
|
||||
- [Risk] raw stream passthrough 可能需要调整 ProviderClient 接口，影响现有测试。→ Mitigation: 将非流式、跨协议流式、同协议 raw 流式分别建模，并补充 E2E 测试。
|
||||
- [Risk] 上游错误透传可能让 OpenAI 客户端看到 Anthropic 错误体。→ Mitigation: 文档明确透明代理边界；只有网关自身错误保证统一格式。
|
||||
- [Risk] SSE frame 级 model 改写需要处理 CRLF、多 data 行和 `[DONE]`。→ Mitigation: 实现轻量 SSE frame parser，覆盖 LF/CRLF、多行 data、解析失败回退原 frame 的测试。
|
||||
- [Risk] 跨协议多模态拒绝会短期限制能力。→ Mitigation: 保留 Canonical 占位和同协议透传，后续多模态 change 可在此基础上扩展。
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. 更新 OpenSpec 和设计文档，明确协议原生路径、base_url、错误和流式边界。
|
||||
2. 校正 adapter 路径识别和 `BuildUrl` 映射测试，确保 OpenAI 接收 `/chat/completions`、Anthropic 接收 `/v1/messages`。
|
||||
3. 修改 `ConversionEngine` 同协议 URL 构建，统一使用 `BuildUrl`，避免核心逻辑绕过 adapter。
|
||||
4. 调整 ProviderClient/ProxyHandler 流式链路，支持 raw passthrough、SSE frame 级 Smart Passthrough 和非 2xx 透传。
|
||||
5. 调整网关层错误输出，非 2xx 上游响应绕过 conversion。
|
||||
6. 补齐单测、集成测试和 E2E 测试。
|
||||
7. 更新 README、backend README 和 `docs/conversion_design.md`。
|
||||
|
||||
由于应用尚未上线，不提供额外路径别名兼容和数据迁移。回滚策略是恢复旧流式 provider client 和错误处理行为。
|
||||
|
||||
## Open Questions
|
||||
|
||||
无。
|
||||
|
||||
@@ -1,42 +0,0 @@
|
||||
## 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，不调整统计模块
|
||||
@@ -1,80 +0,0 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 支持 Anthropic Messages API 端点
|
||||
|
||||
网关 SHALL 提供 Anthropic Messages API 端点供外部应用调用。
|
||||
|
||||
#### Scenario: 成功的非流式请求
|
||||
|
||||
- **WHEN** 应用发送 POST 请求到 `/anthropic/v1/messages`，携带有效的 Anthropic 请求格式（非流式）
|
||||
- **THEN** 网关 SHALL 剥离 `/anthropic` 前缀并将 `/v1/messages` 作为 Anthropic nativePath
|
||||
- **THEN** 网关 SHALL 通过 ConversionEngine 将 Anthropic 请求解码为 Canonical 格式
|
||||
- **THEN** 网关 SHALL 将 Canonical 请求编码为目标供应商协议格式
|
||||
- **THEN** 若上游返回 2xx，网关 SHALL 将供应商的响应通过 ConversionEngine 转换为 Anthropic 格式返回给应用
|
||||
|
||||
#### Scenario: 成功的流式请求
|
||||
|
||||
- **WHEN** 应用发送 POST 请求到 `/anthropic/v1/messages`，携带 `stream: true`
|
||||
- **THEN** 网关 SHALL 通过 ConversionEngine 创建 StreamConverter 或使用同协议流式透传路径
|
||||
- **THEN** 网关 SHALL 将上游协议的 SSE 流转换为 Anthropic 命名事件格式，或在同协议 raw passthrough 下透传 Anthropic SSE
|
||||
- **THEN** 网关 SHALL 使用 `event: <type>\ndata: <json>\n\n` 格式流式返回给应用
|
||||
|
||||
#### Scenario: 同协议透传（Anthropic → Anthropic Provider）
|
||||
|
||||
- **WHEN** 客户端使用 Anthropic 协议且目标供应商也是 Anthropic 协议
|
||||
- **THEN** 网关 SHALL 跳过 Canonical 转换
|
||||
- **THEN** 网关 SHALL 使用 Anthropic adapter 重建上游 URL 和认证 Header
|
||||
- **THEN** 若请求使用统一模型 ID，网关 SHALL 仅通过 Smart Passthrough 改写 model 字段
|
||||
|
||||
### Requirement: 双向协议转换
|
||||
|
||||
网关 SHALL 支持 Anthropic 协议与任意已注册协议间的双向转换。
|
||||
|
||||
#### Scenario: Anthropic 客户端 → OpenAI 供应商
|
||||
|
||||
- **WHEN** 客户端使用 Anthropic 协议且供应商使用 OpenAI 协议
|
||||
- **THEN** SHALL 将 Anthropic MessagesRequest 解码为 CanonicalRequest
|
||||
- **THEN** SHALL 将 CanonicalRequest 编码为 OpenAI ChatCompletionRequest
|
||||
- **THEN** 若上游返回 2xx，SHALL 将 OpenAI ChatCompletionResponse 解码为 CanonicalResponse
|
||||
- **THEN** SHALL 将 CanonicalResponse 编码为 Anthropic MessagesResponse
|
||||
|
||||
#### Scenario: OpenAI 客户端 → Anthropic 供应商
|
||||
|
||||
- **WHEN** 客户端使用 OpenAI 协议且供应商使用 Anthropic 协议
|
||||
- **THEN** SHALL 将 OpenAI ChatCompletionRequest 解码为 CanonicalRequest
|
||||
- **THEN** SHALL 将 CanonicalRequest 编码为 Anthropic MessagesRequest
|
||||
- **THEN** 若上游返回 2xx，SHALL 将 Anthropic MessagesResponse 解码为 CanonicalResponse
|
||||
- **THEN** SHALL 将 CanonicalResponse 编码为 OpenAI ChatCompletionResponse
|
||||
|
||||
#### Scenario: 上游错误透传
|
||||
|
||||
- **WHEN** Anthropic 代理请求收到上游非 2xx HTTP 响应
|
||||
- **THEN** 网关 SHALL 直接透传上游 status code、过滤后的 headers 和 body
|
||||
- **THEN** 网关 SHALL NOT 将上游错误转换为 Anthropic 错误格式
|
||||
|
||||
### Requirement: Anthropic 端点保持 v1 层级
|
||||
|
||||
Anthropic 协议的对外端点 SHALL 保持 `/v1` 层级以匹配 Anthropic 原生路径约定。
|
||||
|
||||
#### Scenario: Claude Code 调用 Anthropic 端点
|
||||
|
||||
- **WHEN** Claude Code 发送请求到 `/anthropic/v1/messages`
|
||||
- **THEN** 网关 SHALL 正确处理请求
|
||||
- **THEN** nativePath SHALL 为 `/v1/messages`
|
||||
- **THEN** 最终上游 URL SHALL 为 `base_url + /v1/messages`
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Anthropic 上游路径映射
|
||||
|
||||
Anthropic adapter SHALL 将剥离协议前缀后的 Anthropic nativePath 映射为 Anthropic 上游路径。
|
||||
|
||||
#### Scenario: Messages 上游路径
|
||||
|
||||
- **WHEN** nativePath 为 `/v1/messages`
|
||||
- **THEN** Anthropic adapter BuildUrl SHALL 返回 `/v1/messages`
|
||||
|
||||
#### Scenario: Models 上游路径
|
||||
|
||||
- **WHEN** nativePath 为 `/v1/models`
|
||||
- **THEN** Anthropic adapter BuildUrl SHALL 返回 `/v1/models`
|
||||
@@ -1,108 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 同协议请求 URL 使用 Adapter 映射
|
||||
|
||||
ConversionEngine SHALL 在同协议透传和 Smart Passthrough 场景下使用 providerAdapter.BuildUrl 构建上游 URL 路径。
|
||||
|
||||
#### Scenario: 同协议 Chat URL 映射
|
||||
|
||||
- **WHEN** clientProtocol == providerProtocol 且 interfaceType 为 CHAT
|
||||
- **THEN** ConversionEngine SHALL 调用 providerAdapter.BuildUrl(nativePath, interfaceType)
|
||||
- **THEN** 上游 URL SHALL 为 provider.BaseURL 与 BuildUrl 返回路径的组合
|
||||
- **THEN** ConversionEngine SHALL NOT 直接将 provider.BaseURL 与 nativePath 拼接为上游 URL
|
||||
|
||||
#### Scenario: 未知接口 URL 映射
|
||||
|
||||
- **WHEN** interfaceType 为 PASSTHROUGH
|
||||
- **THEN** providerAdapter.BuildUrl SHALL 返回适合目标协议的路径或原 nativePath
|
||||
- **THEN** ConversionEngine SHALL 使用该路径构建上游 URL
|
||||
|
||||
### Requirement: SSE Frame 级 Smart Passthrough
|
||||
|
||||
系统 SHALL 支持同协议流式 Smart Passthrough 对 SSE frame 中的 model 字段进行最小化改写。
|
||||
|
||||
#### Scenario: 改写 SSE data JSON
|
||||
|
||||
- **WHEN** 同协议流式响应需要将上游模型名改写为统一模型 ID
|
||||
- **THEN** 系统 SHALL 按 SSE frame 解析上游字节流
|
||||
- **THEN** 对包含 JSON payload 的 `data` 行 SHALL 调用 adapter.RewriteResponseModelName 改写 model 字段
|
||||
- **THEN** SHALL 重建合法 SSE frame 输出
|
||||
|
||||
#### Scenario: 保留 DONE 事件
|
||||
|
||||
- **WHEN** SSE frame 的 data payload 为 `[DONE]`
|
||||
- **THEN** 系统 SHALL 原样输出 `[DONE]`
|
||||
- **THEN** SHALL NOT 尝试按 JSON 解析
|
||||
|
||||
#### Scenario: 改写失败宽容降级
|
||||
|
||||
- **WHEN** SSE frame 解析或 model 改写失败
|
||||
- **THEN** 系统 SHALL 记录 warn 日志
|
||||
- **THEN** SHALL 输出原始 SSE frame
|
||||
- **THEN** SHALL 继续处理后续 frame
|
||||
|
||||
### Requirement: Adapter 模型提取边界
|
||||
|
||||
ProtocolAdapter SHALL 只对明确适配的接口提供 model 提取和 model 改写能力。
|
||||
|
||||
#### Scenario: 已适配接口提取 model
|
||||
|
||||
- **WHEN** ifaceType 为 adapter 明确支持提取 model 的接口
|
||||
- **THEN** ExtractModelName SHALL 按该协议和接口的请求格式提取 model 字段
|
||||
|
||||
#### Scenario: 未适配接口不提取 model
|
||||
|
||||
- **WHEN** ifaceType 为 PASSTHROUGH 或 adapter 未明确支持提取 model 的接口
|
||||
- **THEN** ExtractModelName SHALL 返回错误或空结果
|
||||
- **THEN** 调用方 SHALL 按无 model 请求处理
|
||||
|
||||
### Requirement: 跨协议多模态暂不支持
|
||||
|
||||
ConversionEngine SHALL 在跨协议完整转换中对当前暂不支持的多模态内容返回明确错误。
|
||||
|
||||
#### Scenario: 跨协议请求包含多模态内容块
|
||||
|
||||
- **WHEN** clientProtocol != providerProtocol 且 CanonicalRequest 中包含 image、audio、video 或 file 内容块
|
||||
- **THEN** ConversionEngine SHALL 中断转换
|
||||
- **THEN** SHALL 返回网关层 `UNSUPPORTED_MULTIMODAL` 错误
|
||||
- **THEN** SHALL NOT 静默丢弃多模态内容
|
||||
|
||||
#### Scenario: 同协议多模态请求
|
||||
|
||||
- **WHEN** clientProtocol == providerProtocol 且请求通过 Smart Passthrough 或 raw passthrough 处理
|
||||
- **THEN** 系统 SHALL 保留原始请求体中未改写字段
|
||||
- **THEN** SHALL NOT 因多模态字段存在而执行跨协议多模态校验
|
||||
|
||||
### Requirement: 上游非 2xx 响应不进入转换
|
||||
|
||||
ConversionEngine SHALL 只转换调用方传入的成功响应，ProxyHandler SHALL 在调用转换前过滤上游非 2xx 响应。
|
||||
|
||||
#### Scenario: 非 2xx 响应绕过响应转换
|
||||
|
||||
- **WHEN** 上游响应状态码不是 2xx
|
||||
- **THEN** ProxyHandler SHALL NOT 调用 ConversionEngine.ConvertHttpResponse
|
||||
- **THEN** ProxyHandler SHALL 直接透传该响应
|
||||
|
||||
#### Scenario: 流式非 2xx 响应绕过流式转换
|
||||
|
||||
- **WHEN** 流式请求收到上游非 2xx 响应
|
||||
- **THEN** ProxyHandler SHALL NOT 调用 ConversionEngine.CreateStreamConverter
|
||||
- **THEN** ProxyHandler SHALL 直接透传该响应
|
||||
|
||||
### Requirement: 协议路径来源
|
||||
|
||||
ProtocolAdapter SHALL 以对应协议的本地 API reference 文档作为 URL 识别和 URL 映射的事实来源。
|
||||
|
||||
#### Scenario: OpenAI 路径来源
|
||||
|
||||
- **WHEN** 实现或测试 OpenAI adapter 的 DetectInterfaceType 或 BuildUrl
|
||||
- **THEN** SHALL 参考 `docs/api_reference/openai` 中的接口路径
|
||||
- **THEN** SHALL 忽略 `docs/api_reference/openai/responses` 目录
|
||||
- **THEN** SHALL NOT 因其他协议包含 `/v1` 而给 OpenAI nativePath 添加 `/v1`
|
||||
|
||||
#### Scenario: Anthropic 路径来源
|
||||
|
||||
- **WHEN** 实现或测试 Anthropic adapter 的 DetectInterfaceType 或 BuildUrl
|
||||
- **THEN** SHALL 参考 `docs/api_reference/anthropic` 中的接口路径
|
||||
- **THEN** SHALL 保留文档中接口路径自带的 `/v1` 前缀
|
||||
- **THEN** SHALL NOT 因 OpenAI nativePath 不含 `/v1` 而移除 Anthropic nativePath 中的 `/v1`
|
||||
@@ -1,95 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 网关层代理错误使用应用统一格式
|
||||
|
||||
系统 SHALL 对代理接口中由网关自身产生的错误使用应用统一错误响应格式。
|
||||
|
||||
#### Scenario: 标准网关错误格式
|
||||
|
||||
- **WHEN** 代理接口返回网关层错误
|
||||
- **THEN** SHALL 使用以下 JSON 格式：
|
||||
```json
|
||||
{
|
||||
"error": "错误描述",
|
||||
"code": "ERROR_CODE"
|
||||
}
|
||||
```
|
||||
- **THEN** `error` 字段 SHALL 包含人类可读的错误描述
|
||||
- **THEN** `code` 字段 SHALL 包含机器可读的错误码
|
||||
|
||||
#### Scenario: 网关错误码集合
|
||||
|
||||
- **WHEN** 代理接口返回网关层错误
|
||||
- **THEN** code SHALL 使用以下枚举之一：`INVALID_JSON`、`INVALID_REQUEST`、`INVALID_MODEL_ID`、`MODEL_NOT_FOUND`、`PROVIDER_NOT_FOUND`、`UNSUPPORTED_INTERFACE`、`UNSUPPORTED_MULTIMODAL`、`CONVERSION_FAILED`、`UPSTREAM_UNAVAILABLE`
|
||||
|
||||
### Requirement: 代理接口上游错误透传
|
||||
|
||||
系统 SHALL 对代理接口中已经收到的上游 HTTP 错误响应执行透明透传。
|
||||
|
||||
#### Scenario: 非流式上游非 2xx 响应
|
||||
|
||||
- **WHEN** 非流式代理请求收到上游 HTTP 响应且状态码不是 2xx
|
||||
- **THEN** SHALL 透传上游 status code
|
||||
- **THEN** SHALL 透传过滤 hop-by-hop header 后的上游 headers
|
||||
- **THEN** SHALL 透传上游 body
|
||||
- **THEN** SHALL NOT 将上游错误包装为应用统一错误
|
||||
- **THEN** SHALL NOT 将上游错误转换为客户端协议错误格式
|
||||
|
||||
#### Scenario: 流式上游非 2xx 响应
|
||||
|
||||
- **WHEN** 流式代理请求收到上游 HTTP 响应且状态码不是 2xx
|
||||
- **THEN** SHALL 透传上游 status code
|
||||
- **THEN** SHALL 透传过滤 hop-by-hop header 后的上游 headers
|
||||
- **THEN** SHALL 透传上游 body
|
||||
- **THEN** SHALL NOT 创建 StreamConverter
|
||||
|
||||
### Requirement: 上游不可达错误
|
||||
|
||||
系统 SHALL 在没有收到上游 HTTP 响应时返回网关层错误。
|
||||
|
||||
#### Scenario: 上游连接失败
|
||||
|
||||
- **WHEN** ProviderClient 因 DNS、连接失败、TLS、超时或上下文取消等原因无法获得上游 HTTP 响应
|
||||
- **THEN** SHALL 返回 HTTP 502 或合适的 5xx 状态码
|
||||
- **THEN** SHALL 返回应用统一错误格式
|
||||
- **THEN** code SHALL 为 `UPSTREAM_UNAVAILABLE`
|
||||
|
||||
### Requirement: Hop-by-hop header 过滤
|
||||
|
||||
系统 SHALL 在透传上游错误响应时过滤 hop-by-hop headers。
|
||||
|
||||
#### Scenario: 过滤连接级 header
|
||||
|
||||
- **WHEN** 透传上游错误响应 headers
|
||||
- **THEN** SHALL 过滤 `Connection`、`Transfer-Encoding`、`Keep-Alive`、`Proxy-Authenticate`、`Proxy-Authorization`、`TE`、`Trailer`、`Upgrade`
|
||||
- **THEN** SHALL 保留 `Content-Type` 等普通响应 header
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: JSON 格式错误
|
||||
|
||||
系统 SHALL 对请求体 JSON 格式错误返回明确的错误信息。
|
||||
|
||||
#### Scenario: 请求体 JSON 格式错误
|
||||
|
||||
- **WHEN** 代理请求的请求体不是有效的 JSON 格式，且该接口需要网关解析请求体
|
||||
- **THEN** SHALL 返回 HTTP 400 Bad Request
|
||||
- **THEN** SHALL 返回以下 JSON 格式：
|
||||
```json
|
||||
{
|
||||
"error": "请求体 JSON 格式错误",
|
||||
"code": "INVALID_JSON"
|
||||
}
|
||||
```
|
||||
|
||||
#### Scenario: Smart Passthrough 时请求体 JSON 格式错误
|
||||
|
||||
- **WHEN** 同协议 Smart Passthrough 场景下，请求体 JSON 格式不正确
|
||||
- **THEN** SHALL 返回 HTTP 400 Bad Request
|
||||
- **THEN** SHALL 返回以下 JSON 格式：
|
||||
```json
|
||||
{
|
||||
"error": "请求体 JSON 格式错误",
|
||||
"code": "INVALID_JSON"
|
||||
}
|
||||
```
|
||||
@@ -1,74 +0,0 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 支持 OpenAI Chat Completions API 端点
|
||||
|
||||
网关 SHALL 提供 OpenAI Chat Completions API 端点供外部应用调用。
|
||||
|
||||
#### Scenario: 成功的非流式请求
|
||||
|
||||
- **WHEN** 应用发送 POST 请求到 `/openai/chat/completions`，携带有效的 OpenAI 请求格式（非流式）
|
||||
- **THEN** 网关 SHALL 剥离 `/openai` 前缀并将 `/chat/completions` 作为 OpenAI nativePath
|
||||
- **THEN** 网关 SHALL 通过 ConversionEngine 转换请求
|
||||
- **THEN** 网关 SHALL 将转换后的请求转发到配置的供应商
|
||||
- **THEN** 若上游返回 2xx，网关 SHALL 将供应商的响应通过 ConversionEngine 转换为 OpenAI 格式返回给应用
|
||||
|
||||
#### Scenario: 成功的流式请求
|
||||
|
||||
- **WHEN** 应用发送 POST 请求到 `/openai/chat/completions`，携带 `stream: true`
|
||||
- **THEN** 网关 SHALL 通过 ConversionEngine 创建 StreamConverter 或使用同协议流式透传路径
|
||||
- **THEN** 网关 SHALL 使用 SSE 格式将转换后的响应流式返回给应用
|
||||
- **THEN** 网关 SHALL 在 OpenAI 协议流完成时发送或透传 `data: [DONE]`
|
||||
|
||||
#### Scenario: 同协议透传（OpenAI → OpenAI Provider）
|
||||
|
||||
- **WHEN** 客户端使用 OpenAI 协议且目标供应商也是 OpenAI 协议
|
||||
- **THEN** 网关 SHALL 跳过 Canonical 转换
|
||||
- **THEN** 网关 SHALL 使用 OpenAI adapter 重建上游 URL 和认证 Header
|
||||
- **THEN** 若请求使用统一模型 ID，网关 SHALL 仅通过 Smart Passthrough 改写 model 字段
|
||||
|
||||
### Requirement: 根据模型名称路由请求
|
||||
|
||||
网关 SHALL 根据请求中的 `model` 字段将请求路由到相应的供应商。
|
||||
|
||||
#### Scenario: 有效模型路由
|
||||
|
||||
- **WHEN** 请求包含有效统一模型 ID 格式的 `model` 字段
|
||||
- **AND** 该模型存在且已启用
|
||||
- **THEN** 网关 SHALL 将请求路由到该模型关联的供应商
|
||||
- **THEN** 网关 SHALL 从供应商的 `protocol` 字段获取 providerProtocol
|
||||
|
||||
#### Scenario: 模型未找到
|
||||
|
||||
- **WHEN** 请求包含有效统一模型 ID 格式的 `model` 字段但模型不存在
|
||||
- **THEN** 网关 SHALL 使用应用统一错误格式返回 404 错误
|
||||
|
||||
#### Scenario: 模型已禁用
|
||||
|
||||
- **WHEN** 请求包含已禁用模型的有效统一模型 ID
|
||||
- **THEN** 网关 SHALL 使用应用统一错误格式返回 404 错误
|
||||
|
||||
#### Scenario: 原始模型名兼容透传
|
||||
|
||||
- **WHEN** 请求中的 `model` 字段不是有效统一模型 ID 格式
|
||||
- **THEN** 网关 SHALL 按无可路由 model 请求走 forwardPassthrough
|
||||
|
||||
### Requirement: 跨协议请求转换
|
||||
|
||||
网关 SHALL 对非 OpenAI 兼容供应商的请求和响应通过 ConversionEngine 进行转换处理。
|
||||
|
||||
#### Scenario: 跨协议请求转发
|
||||
|
||||
- **WHEN** 网关收到 OpenAI 协议请求且目标供应商使用不同协议
|
||||
- **THEN** 网关 SHALL 通过 ConversionEngine 将请求转换为目标协议格式
|
||||
- **THEN** 网关 SHALL 使用目标协议的 Adapter 构建 URL 和 Header
|
||||
|
||||
#### Scenario: 扩展层接口代理
|
||||
|
||||
- **WHEN** 网关收到 `/openai/models` 等扩展层接口请求
|
||||
- **THEN** 网关 SHALL 通过本地聚合或 ConversionEngine 转换扩展层接口响应格式
|
||||
|
||||
#### Scenario: 上游错误透传
|
||||
|
||||
- **WHEN** OpenAI 代理请求收到上游非 2xx HTTP 响应
|
||||
- **THEN** 网关 SHALL 直接透传上游 status code、过滤后的 headers 和 body
|
||||
- **THEN** 网关 SHALL NOT 将上游错误转换为 OpenAI 错误格式
|
||||
@@ -1,229 +0,0 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 实现统一代理 Handler
|
||||
|
||||
系统 SHALL 实现统一的 ProxyHandler，替代现有的 OpenAIHandler 和 AnthropicHandler。
|
||||
|
||||
ProxyHandler SHALL 依赖 ConversionEngine、ProviderClient、RoutingService、StatsService。
|
||||
|
||||
#### Scenario: 从 URL 提取客户端协议
|
||||
|
||||
- **WHEN** 收到 `/{protocol}/{path}` 格式的请求
|
||||
- **THEN** SHALL 从 URL 第一段提取 protocol 作为 clientProtocol
|
||||
- **THEN** SHALL 剥离协议前缀得到 nativePath
|
||||
- **THEN** nativePath SHALL 保留剥离协议前缀后的协议原生路径，不添加、不移除版本路径段
|
||||
- **THEN** OpenAI 请求 `/openai/chat/completions` 的 nativePath SHALL 为 `/chat/completions`
|
||||
- **THEN** Anthropic 请求 `/anthropic/v1/messages` 的 nativePath SHALL 为 `/v1/messages`
|
||||
|
||||
#### Scenario: 协议前缀必须是已注册协议
|
||||
|
||||
- **WHEN** 收到的 URL 前缀不是已注册的协议名称
|
||||
- **THEN** SHALL 返回 404 错误
|
||||
- **THEN** 错误响应 SHALL 使用应用统一错误格式
|
||||
|
||||
#### Scenario: 接口类型识别
|
||||
|
||||
- **WHEN** 提取 nativePath 后
|
||||
- **THEN** SHALL 通过 ConversionEngine.convertHttpRequest 内部调用 clientAdapter.detectInterfaceType(nativePath) 识别接口类型
|
||||
- **THEN** 未知路径 SHALL 使用透传模式
|
||||
|
||||
### Requirement: 非流式请求处理流程
|
||||
|
||||
ProxyHandler SHALL 按以下流程处理非流式请求。
|
||||
|
||||
#### Scenario: 完整转换流程
|
||||
|
||||
- **WHEN** 收到非流式请求
|
||||
- **THEN** SHALL 通过客户端 adapter 明确支持的接口规则提取 model
|
||||
- **THEN** SHALL 调用 RoutingService.RouteByModelName(providerID, modelName) 获取路由结果
|
||||
- **THEN** SHALL 从路由结果的 Provider.Protocol 获取 providerProtocol
|
||||
- **THEN** SHALL 构建 TargetProvider（base_url, api_key, model_name, adapter_config）
|
||||
- **THEN** SHALL 调用 engine.convertHttpRequest 获取 HTTPRequestSpec
|
||||
- **THEN** SHALL 调用 providerClient.Send(ctx, requestSpec)
|
||||
- **THEN** 若上游响应状态码为 2xx，SHALL 调用 engine.convertHttpResponse 转换响应
|
||||
- **THEN** SHALL 将转换后的响应返回给客户端
|
||||
|
||||
#### Scenario: 路由失败处理
|
||||
|
||||
- **WHEN** RoutingService.RouteByModelName 返回错误
|
||||
- **THEN** SHALL 使用应用统一错误格式返回网关层错误
|
||||
- **THEN** SHALL 返回适当的 HTTP 状态码
|
||||
|
||||
#### Scenario: 上游请求失败处理
|
||||
|
||||
- **WHEN** ProviderClient.Send 未收到上游 HTTP 响应并返回错误
|
||||
- **THEN** SHALL 使用应用统一错误格式返回网关层错误
|
||||
- **THEN** SHALL 包装原始错误信息用于日志
|
||||
|
||||
#### Scenario: 上游非 2xx 响应透传
|
||||
|
||||
- **WHEN** ProviderClient.Send 收到上游 HTTP 响应且状态码不是 2xx
|
||||
- **THEN** ProxyHandler SHALL NOT 调用 engine.convertHttpResponse
|
||||
- **THEN** SHALL 透传上游 status code
|
||||
- **THEN** SHALL 透传过滤 hop-by-hop header 后的上游 headers
|
||||
- **THEN** SHALL 透传上游 body
|
||||
|
||||
### Requirement: 流式请求处理流程
|
||||
|
||||
ProxyHandler SHALL 按以下流程处理流式请求。
|
||||
|
||||
#### Scenario: 跨协议流式转换流程
|
||||
|
||||
- **WHEN** 请求中 stream=true 且 clientProtocol != providerProtocol
|
||||
- **THEN** SHALL 执行与非流式相同的前置处理（路由、构建 TargetProvider）
|
||||
- **THEN** SHALL 调用 engine.convertHttpRequest 获取 HTTPRequestSpec
|
||||
- **THEN** SHALL 调用 providerClient.SendStream(ctx, requestSpec) 获取流
|
||||
- **THEN** 若上游返回 2xx 流式响应，SHALL 调用 engine.createStreamConverter(clientProtocol, providerProtocol, provider)
|
||||
- **THEN** SHALL 设置响应 Header `Content-Type: text/event-stream`
|
||||
- **THEN** SHALL 对每个流 chunk 调用 converter.processChunk 并写入响应
|
||||
- **THEN** SHALL 在流结束时调用 converter.flush() 刷新缓冲
|
||||
|
||||
#### Scenario: 同协议 raw 流式透传
|
||||
|
||||
- **WHEN** clientProtocol == providerProtocol 且响应不需要 model 改写
|
||||
- **THEN** SHALL 直接将上游 SSE 字节流写入响应
|
||||
- **THEN** SHALL 保留 SSE frame 边界和结束标记
|
||||
- **THEN** SHALL NOT 做任何解析或转换
|
||||
|
||||
#### Scenario: 同协议流式 Smart Passthrough
|
||||
|
||||
- **WHEN** clientProtocol == providerProtocol 且响应需要 model 改写
|
||||
- **THEN** SHALL 按 SSE frame 读取上游流
|
||||
- **THEN** SHALL 仅改写 `data` JSON payload 内的 model 字段
|
||||
- **THEN** SHALL 原样保留 `[DONE]` 结束标记
|
||||
- **THEN** SHALL 重建合法 SSE frame 写回客户端
|
||||
- **THEN** SHALL NOT 做 Canonical decode/encode 转换
|
||||
|
||||
#### Scenario: 流式上游非 2xx 响应透传
|
||||
|
||||
- **WHEN** 流式请求收到上游非 2xx HTTP 响应
|
||||
- **THEN** SHALL NOT 创建 StreamConverter
|
||||
- **THEN** SHALL 透传上游 status code、过滤后的 headers 和 body
|
||||
|
||||
#### Scenario: 流式错误处理
|
||||
|
||||
- **WHEN** 流过程中发生网关层读取或写入错误
|
||||
- **THEN** SHALL 记录错误日志
|
||||
- **THEN** SHALL 关闭响应流
|
||||
|
||||
### Requirement: GET 请求透传
|
||||
|
||||
ProxyHandler SHALL 支持无请求体 GET 请求和未知接口透传。
|
||||
|
||||
#### Scenario: Models 接口本地处理
|
||||
|
||||
- **WHEN** 收到客户端协议的模型列表路径请求，例如 `GET /openai/models` 或 `GET /anthropic/v1/models`
|
||||
- **THEN** SHALL 走模型列表本地聚合流程
|
||||
- **THEN** SHALL NOT 请求上游供应商
|
||||
|
||||
#### Scenario: 未知 GET 接口透传
|
||||
|
||||
- **WHEN** 收到未被 adapter 识别为本地处理接口的 GET 请求
|
||||
- **THEN** SHALL 走 forwardPassthrough 透传到上游供应商
|
||||
- **THEN** SHALL 保留原始 query string
|
||||
|
||||
### Requirement: 代理请求路由
|
||||
|
||||
ProxyHandler SHALL 使用统一模型 ID 路由 adapter 明确支持提取 model 的代理请求。
|
||||
|
||||
#### Scenario: 提取统一模型 ID
|
||||
|
||||
- **WHEN** 收到 adapter 明确支持提取 model 的接口请求（如 Chat、Embeddings 或 Rerank）且请求体非空
|
||||
- **THEN** SHALL 调用客户端协议 adapter 的 `ExtractModelName(body, ifaceType)` 提取 model 值
|
||||
- **THEN** SHALL 调用 `ParseUnifiedModelID` 解析得到 providerID 和 modelName
|
||||
- **THEN** SHALL 调用 `RoutingService.RouteByModelName(providerID, modelName)` 路由
|
||||
|
||||
#### Scenario: 未知接口不猜测 model
|
||||
|
||||
- **WHEN** 收到 adapter 未明确支持提取 model 的接口请求
|
||||
- **THEN** ProxyHandler SHALL NOT 尝试通用解析顶层 model 字段
|
||||
- **THEN** SHALL 按无 model 请求走 forwardPassthrough
|
||||
|
||||
#### Scenario: GET 请求或无请求体
|
||||
|
||||
- **WHEN** 收到 GET 请求或请求体为空或请求体中无法提取 model 字段
|
||||
- **THEN** SHALL 走 forwardPassthrough 透传到上游供应商
|
||||
|
||||
#### Scenario: 无效的统一模型 ID
|
||||
|
||||
- **WHEN** adapter 已提取 model 字段但该字段不是有效的统一模型 ID 格式（不含 `/`）
|
||||
- **THEN** SHALL 走 forwardPassthrough 透传到上游供应商
|
||||
|
||||
#### Scenario: 模型不存在
|
||||
|
||||
- **WHEN** 解析统一模型 ID 后，数据库中找不到对应的 provider_id + model_name 组合
|
||||
- **THEN** SHALL 返回应用统一错误响应，状态码为 404
|
||||
|
||||
#### Scenario: 模型已禁用
|
||||
|
||||
- **WHEN** 解析统一模型 ID 后，对应的模型 enabled 为 false
|
||||
- **THEN** SHALL 返回应用统一错误响应，状态码为 404
|
||||
|
||||
#### Scenario: 供应商已禁用
|
||||
|
||||
- **WHEN** 解析统一模型 ID 后，对应的供应商 enabled 为 false
|
||||
- **THEN** SHALL 返回应用统一错误响应，状态码为 404
|
||||
|
||||
### Requirement: 同协议 Smart Passthrough
|
||||
|
||||
当客户端协议与供应商协议相同时，ProxyHandler SHALL 使用 Smart Passthrough 处理 adapter 明确支持的 Chat、Embedding、Rerank 请求。
|
||||
|
||||
#### Scenario: 同协议非流式请求
|
||||
|
||||
- **WHEN** 客户端协议 == 供应商协议，且为非流式请求
|
||||
- **THEN** SHALL 调用 adapter 的 `RewriteRequestModelName(body, modelName, ifaceType)` 将请求体中 model 从统一 ID 改写为上游模型名
|
||||
- **THEN** SHALL 使用 providerAdapter.BuildUrl(nativePath, ifaceType) 构建上游 URL 路径
|
||||
- **THEN** SHALL 使用 providerAdapter.BuildHeaders(provider) 构建 Headers
|
||||
- **THEN** SHALL 发送改写后的请求体到上游
|
||||
- **THEN** 若上游返回 2xx，SHALL 调用 adapter 的 `RewriteResponseModelName(resp.Body, unifiedModelID, ifaceType)` 将响应中 model 从上游名改写为统一 ID
|
||||
- **THEN** SHALL NOT 对 body 做 Canonical 全量 decode → encode，保持未改写字段的 JSON 内容和类型不变，但不承诺保留原始字节顺序或空白
|
||||
|
||||
#### Scenario: 同协议流式请求
|
||||
|
||||
- **WHEN** 客户端协议 == 供应商协议，且为流式请求
|
||||
- **THEN** SHALL 对请求体做 `RewriteRequestModelName` 改写 model 字段
|
||||
- **THEN** SHALL 使用 providerAdapter.BuildUrl(nativePath, ifaceType) 构建上游 URL 路径
|
||||
- **THEN** SHALL 按 raw passthrough 或 SSE frame 级 Smart Passthrough 处理响应流
|
||||
- **THEN** SHALL NOT 对 chunk 做 Canonical 全量 decode → encode
|
||||
|
||||
#### Scenario: Smart Passthrough 保真性
|
||||
|
||||
- **WHEN** 客户端发送含未知参数的请求（如 `{"model":"openai/gpt-4","some_new_param":"value"}`）
|
||||
- **THEN** 上游 SHALL 收到 `{"model":"gpt-4","some_new_param":"value"}`
|
||||
- **THEN** `some_new_param` SHALL 保持原始值不变，不丢失、不改变类型
|
||||
|
||||
### Requirement: 模型列表本地聚合
|
||||
|
||||
ProxyHandler SHALL 从数据库聚合返回模型列表，不再透传上游。
|
||||
|
||||
#### Scenario: 客户端协议模型列表路径
|
||||
|
||||
- **WHEN** 收到客户端协议的模型列表路径请求，例如 `GET /openai/models` 或 `GET /anthropic/v1/models`
|
||||
- **THEN** SHALL 从数据库查询所有 enabled 的模型（关联 enabled 的供应商）
|
||||
- **THEN** SHALL 组装 `CanonicalModelList`，每个模型的 ID 字段为统一模型 ID（`provider_id/model_name`），Name 字段为 model_name，OwnedBy 字段为 provider_id
|
||||
- **THEN** SHALL 使用客户端协议的 adapter 编码响应
|
||||
- **THEN** SHALL NOT 请求上游供应商
|
||||
|
||||
#### Scenario: 无可用模型
|
||||
|
||||
- **WHEN** 数据库中没有 enabled 的模型
|
||||
- **THEN** SHALL 返回空列表
|
||||
|
||||
### Requirement: 模型详情本地查询
|
||||
|
||||
ProxyHandler SHALL 从数据库查询返回模型详情，不再透传上游。
|
||||
|
||||
#### Scenario: 客户端协议模型详情路径
|
||||
|
||||
- **WHEN** 收到客户端协议的模型详情路径请求，例如 `GET /openai/models/{provider_id}/{model_name}` 或 `GET /anthropic/v1/models/{provider_id}/{model_name}`
|
||||
- **THEN** SHALL 调用 adapter 的 `ExtractUnifiedModelID` 提取统一模型 ID
|
||||
- **THEN** SHALL 解析统一模型 ID 得到 providerID 和 modelName
|
||||
- **THEN** SHALL 从数据库查询对应的模型和供应商
|
||||
- **THEN** SHALL 组装 `CanonicalModelInfo`，ID 字段为统一模型 ID（`provider_id/model_name`），Name 字段为 model_name，OwnedBy 字段为 provider_id
|
||||
- **THEN** SHALL 使用客户端协议的 adapter 编码响应
|
||||
- **THEN** SHALL NOT 请求上游供应商
|
||||
|
||||
#### Scenario: 模型详情不存在
|
||||
|
||||
- **WHEN** 统一模型 ID 对应的模型不存在或已禁用
|
||||
- **THEN** SHALL 返回应用统一错误响应，状态码为 404
|
||||
@@ -1,51 +0,0 @@
|
||||
## 1. 路径与 Adapter 映射
|
||||
|
||||
- [x] 1.0 对照 docs/api_reference/openai（忽略 responses 目录）和 docs/api_reference/anthropic 确认本次涉及接口的协议原生路径，并将确认结果写入对应 adapter 测试用例
|
||||
- [x] 1.1 确认 OpenAI adapter 识别剥离协议前缀后的 `/chat/completions`、`/models`、`/embeddings`、`/rerank` 路径并补充测试
|
||||
- [x] 1.2 确认 Anthropic adapter 识别剥离协议前缀后的 `/v1/messages`、`/v1/models`、`/v1/models/{id}` 路径并补充测试
|
||||
- [x] 1.3 补充 BuildUrl 测试，确认 OpenAI `base_url=http://xxx.com/v1` 组合为 `/v1/chat/completions`，Anthropic `base_url=http://xxx.com` 组合为 `/v1/messages`
|
||||
- [x] 1.4 修改 ConversionEngine 同协议请求 URL 构建逻辑，统一使用 providerAdapter.BuildUrl(nativePath, interfaceType)
|
||||
- [x] 1.5 更新 ProxyHandler 和路由测试，确认网关只剥离协议前缀，不对 nativePath 添加或移除 `/v1`
|
||||
|
||||
## 2. 错误响应与上游透传
|
||||
|
||||
- [x] 2.1 增加网关层代理错误响应工具，统一输出 `{error, code}` 和对应 HTTP 状态码
|
||||
- [x] 2.2 将路由失败、JSON 解析失败、转换失败、上游不可达等网关错误改为应用统一错误格式
|
||||
- [x] 2.3 在非流式 handler 中对上游非 2xx 响应绕过 ConvertHttpResponse 并透传 status、过滤后的 headers、body
|
||||
- [x] 2.4 实现 hop-by-hop response header 过滤并补充单元测试
|
||||
- [x] 2.5 调整 ProviderClient 或调用方错误返回，使未收到上游 HTTP 响应时可返回 `UPSTREAM_UNAVAILABLE`
|
||||
|
||||
## 3. 流式链路
|
||||
|
||||
- [x] 3.1 调整 ProviderClient 流式能力，使 handler 可区分上游 2xx 流、上游非 2xx 响应和上游不可达错误
|
||||
- [x] 3.2 实现同协议无 model 改写时的 raw SSE passthrough，保留 frame 边界和 `[DONE]`
|
||||
- [x] 3.3 实现 SSE frame 解析与重建工具，覆盖 LF、CRLF、多 data 行和空 frame
|
||||
- [x] 3.4 实现同协议流式 Smart Passthrough，在 SSE data JSON 内改写 model，失败时输出原 frame 并继续
|
||||
- [x] 3.5 确保跨协议流式仍走 provider StreamDecoder 到 client StreamEncoder 的 CanonicalStreamConverter
|
||||
|
||||
## 4. 路由与能力边界
|
||||
|
||||
- [x] 4.1 明确 adapter 的 ExtractModelName 只支持已适配接口，PASSTHROUGH 或未适配接口返回错误或空结果
|
||||
- [x] 4.2 修改 ProxyHandler，未知接口不做通用顶层 model 猜测，按无 model 请求走 forwardPassthrough
|
||||
- [x] 4.3 保留原始模型名兼容透传逻辑，有效统一模型 ID 但路由失败时返回 `MODEL_NOT_FOUND`
|
||||
- [x] 4.4 在跨协议转换中检测 image、audio、video、file 内容块并返回 `UNSUPPORTED_MULTIMODAL`
|
||||
- [x] 4.5 确保同协议 Smart Passthrough 不因多模态字段存在而拒绝请求
|
||||
|
||||
## 5. 测试
|
||||
|
||||
- [x] 5.1 补充 OpenAI `/openai/chat/completions` 和 Anthropic `/anthropic/v1/messages` 的 handler、E2E 测试
|
||||
- [x] 5.2 补充 nativePath 保持协议原生路径的测试，断言 OpenAI adapter 接收 `/chat/completions`、Anthropic adapter 接收 `/v1/messages`
|
||||
- [x] 5.3 补充同协议流式 raw passthrough 测试，断言 SSE frame 边界和 `[DONE]` 保留
|
||||
- [x] 5.4 补充同协议流式 Smart Passthrough 测试，断言响应 model 改写为统一模型 ID
|
||||
- [x] 5.5 补充非流式和流式上游非 2xx 错误透传测试
|
||||
- [x] 5.6 补充网关层错误统一格式测试，覆盖 `INVALID_JSON`、`MODEL_NOT_FOUND`、`CONVERSION_FAILED`、`UPSTREAM_UNAVAILABLE`
|
||||
- [x] 5.7 补充未知接口不提取 model 的透传测试
|
||||
- [x] 5.8 补充跨协议多模态返回 `UNSUPPORTED_MULTIMODAL` 测试
|
||||
|
||||
## 6. 文档与验证
|
||||
|
||||
- [x] 6.1 更新 README.md 的代理接口路径、错误边界和 base_url 约定说明
|
||||
- [x] 6.2 更新 backend/README.md 的代理接口路径、错误边界和流式透传说明
|
||||
- [x] 6.3 更新 docs/conversion_design.md，使路径、三车道流式行为、错误处理和 adapter 模型提取边界与实现一致
|
||||
- [x] 6.4 运行 `go test ./internal/conversion/...` 并确保通过
|
||||
- [x] 6.5 运行 `go test ./tests/integration` 并确保通过
|
||||
@@ -13,22 +13,24 @@
|
||||
#### Scenario: 成功的非流式请求
|
||||
|
||||
- **WHEN** 应用发送 POST 请求到 `/anthropic/v1/messages`，携带有效的 Anthropic 请求格式（非流式）
|
||||
- **THEN** 网关 SHALL 剥离 `/anthropic` 前缀并将 `/v1/messages` 作为 Anthropic nativePath
|
||||
- **THEN** 网关 SHALL 通过 ConversionEngine 将 Anthropic 请求解码为 Canonical 格式
|
||||
- **THEN** 网关 SHALL 将 Canonical 请求编码为目标供应商协议格式
|
||||
- **THEN** 网关 SHALL 将供应商的响应通过 ConversionEngine 转换为 Anthropic 格式返回给应用
|
||||
- **THEN** 若上游返回 2xx，网关 SHALL 将供应商的响应通过 ConversionEngine 转换为 Anthropic 格式返回给应用
|
||||
|
||||
#### Scenario: 成功的流式请求
|
||||
|
||||
- **WHEN** 应用发送 POST 请求到 `/anthropic/v1/messages`，携带 `stream: true`
|
||||
- **THEN** 网关 SHALL 通过 ConversionEngine 创建 StreamConverter
|
||||
- **THEN** 网关 SHALL 将上游协议的 SSE 流转换为 Anthropic 命名事件格式
|
||||
- **THEN** 网关 SHALL 通过 ConversionEngine 创建 StreamConverter 或使用同协议流式透传路径
|
||||
- **THEN** 网关 SHALL 将上游协议的 SSE 流转换为 Anthropic 命名事件格式，或在同协议 raw passthrough 下透传 Anthropic SSE
|
||||
- **THEN** 网关 SHALL 使用 `event: <type>\ndata: <json>\n\n` 格式流式返回给应用
|
||||
|
||||
#### Scenario: 同协议透传（Anthropic → Anthropic Provider）
|
||||
|
||||
- **WHEN** 客户端使用 Anthropic 协议且目标供应商也是 Anthropic 协议
|
||||
- **THEN** 网关 SHALL 跳过 Canonical 转换，仅重建认证 Header 后原样转发
|
||||
- **THEN** 请求和响应 Body SHALL 保持原样
|
||||
- **THEN** 网关 SHALL 跳过 Canonical 转换
|
||||
- **THEN** 网关 SHALL 使用 Anthropic adapter 重建上游 URL 和认证 Header
|
||||
- **THEN** 若请求使用统一模型 ID，网关 SHALL 仅通过 Smart Passthrough 改写 model 字段
|
||||
|
||||
### Requirement: 双向协议转换
|
||||
|
||||
@@ -39,7 +41,7 @@
|
||||
- **WHEN** 客户端使用 Anthropic 协议且供应商使用 OpenAI 协议
|
||||
- **THEN** SHALL 将 Anthropic MessagesRequest 解码为 CanonicalRequest
|
||||
- **THEN** SHALL 将 CanonicalRequest 编码为 OpenAI ChatCompletionRequest
|
||||
- **THEN** SHALL 将 OpenAI ChatCompletionResponse 解码为 CanonicalResponse
|
||||
- **THEN** 若上游返回 2xx，SHALL 将 OpenAI ChatCompletionResponse 解码为 CanonicalResponse
|
||||
- **THEN** SHALL 将 CanonicalResponse 编码为 Anthropic MessagesResponse
|
||||
|
||||
#### Scenario: OpenAI 客户端 → Anthropic 供应商
|
||||
@@ -47,12 +49,18 @@
|
||||
- **WHEN** 客户端使用 OpenAI 协议且供应商使用 Anthropic 协议
|
||||
- **THEN** SHALL 将 OpenAI ChatCompletionRequest 解码为 CanonicalRequest
|
||||
- **THEN** SHALL 将 CanonicalRequest 编码为 Anthropic MessagesRequest
|
||||
- **THEN** SHALL 将 Anthropic MessagesResponse 解码为 CanonicalResponse
|
||||
- **THEN** 若上游返回 2xx，SHALL 将 Anthropic MessagesResponse 解码为 CanonicalResponse
|
||||
- **THEN** SHALL 将 CanonicalResponse 编码为 OpenAI ChatCompletionResponse
|
||||
|
||||
#### Scenario: 上游错误透传
|
||||
|
||||
- **WHEN** Anthropic 代理请求收到上游非 2xx HTTP 响应
|
||||
- **THEN** 网关 SHALL 直接透传上游 status code、过滤后的 headers 和 body
|
||||
- **THEN** 网关 SHALL NOT 将上游错误转换为 Anthropic 错误格式
|
||||
|
||||
### Requirement: Anthropic 端点保持 v1 层级
|
||||
|
||||
Anthropic 协议的对外端点 SHALL 保持 `/v1` 层级以兼容 Claude Code。
|
||||
Anthropic 协议的对外端点 SHALL 保持 `/v1` 层级以匹配 Anthropic 原生路径约定。
|
||||
|
||||
#### Scenario: Claude Code 调用 Anthropic 端点
|
||||
|
||||
@@ -60,3 +68,17 @@ Anthropic 协议的对外端点 SHALL 保持 `/v1` 层级以兼容 Claude Code
|
||||
- **THEN** 网关 SHALL 正确处理请求
|
||||
- **THEN** nativePath SHALL 为 `/v1/messages`
|
||||
- **THEN** 最终上游 URL SHALL 为 `base_url + /v1/messages`
|
||||
|
||||
### Requirement: Anthropic 上游路径映射
|
||||
|
||||
Anthropic adapter SHALL 将剥离协议前缀后的 Anthropic nativePath 映射为 Anthropic 上游路径。
|
||||
|
||||
#### Scenario: Messages 上游路径
|
||||
|
||||
- **WHEN** nativePath 为 `/v1/messages`
|
||||
- **THEN** Anthropic adapter BuildUrl SHALL 返回 `/v1/messages`
|
||||
|
||||
#### Scenario: Models 上游路径
|
||||
|
||||
- **WHEN** nativePath 为 `/v1/models`
|
||||
- **THEN** Anthropic adapter BuildUrl SHALL 返回 `/v1/models`
|
||||
|
||||
@@ -325,3 +325,137 @@ TargetProvider 的 ModelName 字段 SHALL 存储上游供应商的模型名称
|
||||
|
||||
- **WHEN** 协议适配器编码请求时
|
||||
- **THEN** SHALL 使用 `TargetProvider.ModelName` 作为发给上游的 `model` 字段值（值为路由结果中的 model_name）
|
||||
|
||||
### Requirement: 同协议请求 URL 使用 Adapter 映射
|
||||
|
||||
ConversionEngine SHALL 在同协议透传和 Smart Passthrough 场景下使用 providerAdapter.BuildUrl 构建上游 URL 路径。
|
||||
|
||||
#### Scenario: 同协议 Chat URL 映射
|
||||
|
||||
- **WHEN** clientProtocol == providerProtocol 且 interfaceType 为 CHAT
|
||||
- **THEN** ConversionEngine SHALL 调用 providerAdapter.BuildUrl(nativePath, interfaceType)
|
||||
- **THEN** 上游 URL SHALL 为 provider.BaseURL 与 BuildUrl 返回路径的组合
|
||||
- **THEN** ConversionEngine SHALL NOT 直接将 provider.BaseURL 与 nativePath 拼接为上游 URL
|
||||
|
||||
#### Scenario: 未知接口 URL 映射
|
||||
|
||||
- **WHEN** interfaceType 为 PASSTHROUGH
|
||||
- **THEN** providerAdapter.BuildUrl SHALL 返回适合目标协议的路径或原 nativePath
|
||||
- **THEN** ConversionEngine SHALL 使用该路径构建上游 URL
|
||||
|
||||
### Requirement: 上游 URL 构建使用目标协议 Adapter
|
||||
|
||||
ConversionEngine SHALL 始终使用目标供应商协议的 adapter 构建上游 URL 路径，避免客户端协议 nativePath 中的版本段泄露到目标协议上游 URL。
|
||||
|
||||
#### Scenario: OpenAI 客户端到 OpenAI 供应商
|
||||
|
||||
- **WHEN** clientProtocol 为 `openai`，providerProtocol 为 `openai`，nativePath 为 `/v1/chat/completions`
|
||||
- **THEN** ConversionEngine SHALL 调用 OpenAI adapter 的 `BuildUrl(nativePath, InterfaceTypeChat)`
|
||||
- **THEN** 上游 path SHALL 为 `/chat/completions`
|
||||
- **THEN** 当 provider.base_url 为 `https://api.openai.com/v1` 时，最终上游 URL SHALL 为 `https://api.openai.com/v1/chat/completions`
|
||||
|
||||
#### Scenario: OpenAI 客户端到 Anthropic 供应商
|
||||
|
||||
- **WHEN** clientProtocol 为 `openai`，providerProtocol 为 `anthropic`，nativePath 为 `/v1/chat/completions`
|
||||
- **THEN** ConversionEngine SHALL 使用 OpenAI adapter 识别接口类型为 `InterfaceTypeChat`
|
||||
- **THEN** ConversionEngine SHALL 调用 Anthropic adapter 的 `BuildUrl(nativePath, InterfaceTypeChat)`
|
||||
- **THEN** 上游 path SHALL 为 `/v1/messages`
|
||||
- **THEN** OpenAI nativePath 中的 `/v1/chat/completions` SHALL NOT 被直接拼接到 Anthropic 上游 URL
|
||||
|
||||
#### Scenario: Anthropic 客户端到 OpenAI 供应商
|
||||
|
||||
- **WHEN** clientProtocol 为 `anthropic`，providerProtocol 为 `openai`，nativePath 为 `/v1/messages`
|
||||
- **THEN** ConversionEngine SHALL 使用 Anthropic adapter 识别接口类型为 `InterfaceTypeChat`
|
||||
- **THEN** ConversionEngine SHALL 调用 OpenAI adapter 的 `BuildUrl(nativePath, InterfaceTypeChat)`
|
||||
- **THEN** 上游 path SHALL 为 `/chat/completions`
|
||||
- **THEN** 当 provider.base_url 为 `https://api.openai.com/v1` 时，最终上游 URL SHALL 为 `https://api.openai.com/v1/chat/completions`
|
||||
|
||||
### Requirement: SSE Frame 级 Smart Passthrough
|
||||
|
||||
系统 SHALL 支持同协议流式 Smart Passthrough 对 SSE frame 中的 model 字段进行最小化改写。
|
||||
|
||||
#### Scenario: 改写 SSE data JSON
|
||||
|
||||
- **WHEN** 同协议流式响应需要将上游模型名改写为统一模型 ID
|
||||
- **THEN** 系统 SHALL 按 SSE frame 解析上游字节流
|
||||
- **THEN** 对包含 JSON payload 的 `data` 行 SHALL 调用 adapter.RewriteResponseModelName 改写 model 字段
|
||||
- **THEN** SHALL 重建合法 SSE frame 输出
|
||||
|
||||
#### Scenario: 保留 DONE 事件
|
||||
|
||||
- **WHEN** SSE frame 的 data payload 为 `[DONE]`
|
||||
- **THEN** 系统 SHALL 原样输出 `[DONE]`
|
||||
- **THEN** SHALL NOT 尝试按 JSON 解析
|
||||
|
||||
#### Scenario: 改写失败宽容降级
|
||||
|
||||
- **WHEN** SSE frame 解析或 model 改写失败
|
||||
- **THEN** 系统 SHALL 记录 warn 日志
|
||||
- **THEN** SHALL 输出原始 SSE frame
|
||||
- **THEN** SHALL 继续处理后续 frame
|
||||
|
||||
### Requirement: Adapter 模型提取边界
|
||||
|
||||
ProtocolAdapter SHALL 只对明确适配的接口提供 model 提取和 model 改写能力。
|
||||
|
||||
#### Scenario: 已适配接口提取 model
|
||||
|
||||
- **WHEN** ifaceType 为 adapter 明确支持提取 model 的接口
|
||||
- **THEN** ExtractModelName SHALL 按该协议和接口的请求格式提取 model 字段
|
||||
|
||||
#### Scenario: 未适配接口不提取 model
|
||||
|
||||
- **WHEN** ifaceType 为 PASSTHROUGH 或 adapter 未明确支持提取 model 的接口
|
||||
- **THEN** ExtractModelName SHALL 返回错误或空结果
|
||||
- **THEN** 调用方 SHALL 按无 model 请求处理
|
||||
|
||||
### Requirement: 跨协议多模态暂不支持
|
||||
|
||||
ConversionEngine SHALL 在跨协议完整转换中对当前暂不支持的多模态内容返回明确错误。
|
||||
|
||||
#### Scenario: 跨协议请求包含多模态内容块
|
||||
|
||||
- **WHEN** clientProtocol != providerProtocol 且 CanonicalRequest 中包含 image、audio、video 或 file 内容块
|
||||
- **THEN** ConversionEngine SHALL 中断转换
|
||||
- **THEN** SHALL 返回网关层 `UNSUPPORTED_MULTIMODAL` 错误
|
||||
- **THEN** SHALL NOT 静默丢弃多模态内容
|
||||
|
||||
#### Scenario: 同协议多模态请求
|
||||
|
||||
- **WHEN** clientProtocol == providerProtocol 且请求通过 Smart Passthrough 或 raw passthrough 处理
|
||||
- **THEN** 系统 SHALL 保留原始请求体中未改写字段
|
||||
- **THEN** SHALL NOT 因多模态字段存在而执行跨协议多模态校验
|
||||
|
||||
### Requirement: 上游非 2xx 响应不进入转换
|
||||
|
||||
ConversionEngine SHALL 只转换调用方传入的成功响应，ProxyHandler SHALL 在调用转换前过滤上游非 2xx 响应。
|
||||
|
||||
#### Scenario: 非 2xx 响应绕过响应转换
|
||||
|
||||
- **WHEN** 上游响应状态码不是 2xx
|
||||
- **THEN** ProxyHandler SHALL NOT 调用 ConversionEngine.ConvertHttpResponse
|
||||
- **THEN** ProxyHandler SHALL 直接透传该响应
|
||||
|
||||
#### Scenario: 流式非 2xx 响应绕过流式转换
|
||||
|
||||
- **WHEN** 流式请求收到上游非 2xx 响应
|
||||
- **THEN** ProxyHandler SHALL NOT 调用 ConversionEngine.CreateStreamConverter
|
||||
- **THEN** ProxyHandler SHALL 直接透传该响应
|
||||
|
||||
### Requirement: 协议路径来源
|
||||
|
||||
ProtocolAdapter SHALL 以对应协议的本地 API reference 文档作为 URL 识别和 URL 映射的事实来源。
|
||||
|
||||
#### Scenario: OpenAI 路径来源
|
||||
|
||||
- **WHEN** 实现或测试 OpenAI adapter 的 DetectInterfaceType 或 BuildUrl
|
||||
- **THEN** SHALL 参考 `docs/api_reference/openai` 中的接口路径
|
||||
- **THEN** SHALL 忽略 `docs/api_reference/openai/responses` 目录
|
||||
- **THEN** SHALL NOT 因其他协议包含 `/v1` 而给 OpenAI nativePath 添加 `/v1`
|
||||
|
||||
#### Scenario: Anthropic 路径来源
|
||||
|
||||
- **WHEN** 实现或测试 Anthropic adapter 的 DetectInterfaceType 或 BuildUrl
|
||||
- **THEN** SHALL 参考 `docs/api_reference/anthropic` 中的接口路径
|
||||
- **THEN** SHALL 保留文档中接口路径自带的 `/v1` 前缀
|
||||
- **THEN** SHALL NOT 因 OpenAI nativePath 不含 `/v1` 而移除 Anthropic nativePath 中的 `/v1`
|
||||
|
||||
@@ -73,21 +73,46 @@ TBD - 提供跨平台桌面应用支持，将后端服务与前端静态资源
|
||||
|
||||
### Requirement: 静态文件服务
|
||||
|
||||
系统 SHALL 通过 Gin 同时服务 API 和前端静态资源。
|
||||
系统 SHALL 通过 Gin 同时服务 API、协议代理和前端静态资源。
|
||||
|
||||
#### Scenario: API 请求路由
|
||||
|
||||
- **WHEN** 请求路径以 `/api/` 或 `/v1/` 开头
|
||||
- **THEN** 请求由现有业务 handler 处理
|
||||
- **WHEN** 请求路径以 `/api/` 或 `/health` 开头
|
||||
- **THEN** 请求由现有业务 handler 处理或返回 API 风格 404
|
||||
|
||||
#### Scenario: 协议代理请求路由
|
||||
|
||||
- **WHEN** 请求路径以 `/openai/` 或 `/anthropic/` 开头
|
||||
- **THEN** 请求 SHALL 被视为协议代理请求或返回 API 风格 404
|
||||
- **THEN** 请求 SHALL NOT 返回前端 `index.html`
|
||||
|
||||
#### Scenario: OpenAI 代理路由
|
||||
|
||||
- **WHEN** desktop 模式收到 `/openai/v1/chat/completions` 请求
|
||||
- **THEN** 请求 SHALL 进入 ProxyHandler
|
||||
- **THEN** ProxyHandler SHALL 获取 clientProtocol 为 `openai`
|
||||
|
||||
#### Scenario: Anthropic 代理路由
|
||||
|
||||
- **WHEN** desktop 模式收到 `/anthropic/v1/messages` 请求
|
||||
- **THEN** 请求 SHALL 进入 ProxyHandler
|
||||
- **THEN** ProxyHandler SHALL 获取 clientProtocol 为 `anthropic`
|
||||
|
||||
#### Scenario: 静态资源路由
|
||||
|
||||
- **WHEN** 请求路径为 `/assets/*`
|
||||
- **THEN** 返回嵌入的前端静态资源文件
|
||||
- **THEN** 请求 SHALL NOT 被协议代理路由处理
|
||||
|
||||
#### Scenario: Favicon 路由
|
||||
|
||||
- **WHEN** 请求路径为 `/favicon.svg`
|
||||
- **THEN** 返回嵌入的前端 favicon 资源
|
||||
- **THEN** 请求 SHALL NOT 被协议代理路由处理
|
||||
|
||||
#### Scenario: SPA 路由回退
|
||||
|
||||
- **WHEN** 请求路径不匹配任何 API 或静态资源路由
|
||||
- **WHEN** 请求路径不匹配任何 API、协议代理或静态资源路由
|
||||
- **THEN** 返回 `index.html`（支持前端 SPA 路由）
|
||||
|
||||
### Requirement: 端口冲突检测
|
||||
|
||||
@@ -23,6 +23,70 @@
|
||||
- **THEN** `error` 字段 SHALL 包含人类可读的错误描述
|
||||
- **THEN** `code` 字段 SHALL 包含机器可读的错误代码（可选）
|
||||
|
||||
### Requirement: 网关层代理错误使用应用统一格式
|
||||
|
||||
系统 SHALL 对代理接口中由网关自身产生的错误使用应用统一错误响应格式。
|
||||
|
||||
#### Scenario: 标准网关错误格式
|
||||
|
||||
- **WHEN** 代理接口返回网关层错误
|
||||
- **THEN** SHALL 使用以下 JSON 格式：
|
||||
```json
|
||||
{
|
||||
"error": "错误描述",
|
||||
"code": "ERROR_CODE"
|
||||
}
|
||||
```
|
||||
- **THEN** `error` 字段 SHALL 包含人类可读的错误描述
|
||||
- **THEN** `code` 字段 SHALL 包含机器可读的错误码
|
||||
|
||||
#### Scenario: 网关错误码集合
|
||||
|
||||
- **WHEN** 代理接口返回网关层错误
|
||||
- **THEN** code SHALL 使用以下枚举之一：`INVALID_JSON`、`INVALID_REQUEST`、`INVALID_MODEL_ID`、`MODEL_NOT_FOUND`、`PROVIDER_NOT_FOUND`、`UNSUPPORTED_INTERFACE`、`UNSUPPORTED_MULTIMODAL`、`CONVERSION_FAILED`、`UPSTREAM_UNAVAILABLE`
|
||||
|
||||
### Requirement: 代理接口上游错误透传
|
||||
|
||||
系统 SHALL 对代理接口中已经收到的上游 HTTP 错误响应执行透明透传。
|
||||
|
||||
#### Scenario: 非流式上游非 2xx 响应
|
||||
|
||||
- **WHEN** 非流式代理请求收到上游 HTTP 响应且状态码不是 2xx
|
||||
- **THEN** SHALL 透传上游 status code
|
||||
- **THEN** SHALL 透传过滤 hop-by-hop header 后的上游 headers
|
||||
- **THEN** SHALL 透传上游 body
|
||||
- **THEN** SHALL NOT 将上游错误包装为应用统一错误
|
||||
- **THEN** SHALL NOT 将上游错误转换为客户端协议错误格式
|
||||
|
||||
#### Scenario: 流式上游非 2xx 响应
|
||||
|
||||
- **WHEN** 流式代理请求收到上游 HTTP 响应且状态码不是 2xx
|
||||
- **THEN** SHALL 透传上游 status code
|
||||
- **THEN** SHALL 透传过滤 hop-by-hop header 后的上游 headers
|
||||
- **THEN** SHALL 透传上游 body
|
||||
- **THEN** SHALL NOT 创建 StreamConverter
|
||||
|
||||
### Requirement: 上游不可达错误
|
||||
|
||||
系统 SHALL 在没有收到上游 HTTP 响应时返回网关层错误。
|
||||
|
||||
#### Scenario: 上游连接失败
|
||||
|
||||
- **WHEN** ProviderClient 因 DNS、连接失败、TLS、超时或上下文取消等原因无法获得上游 HTTP 响应
|
||||
- **THEN** SHALL 返回 HTTP 502 或合适的 5xx 状态码
|
||||
- **THEN** SHALL 返回应用统一错误格式
|
||||
- **THEN** code SHALL 为 `UPSTREAM_UNAVAILABLE`
|
||||
|
||||
### Requirement: Hop-by-hop header 过滤
|
||||
|
||||
系统 SHALL 在透传上游错误响应时过滤 hop-by-hop headers。
|
||||
|
||||
#### Scenario: 过滤连接级 header
|
||||
|
||||
- **WHEN** 透传上游错误响应 headers
|
||||
- **THEN** SHALL 过滤 `Connection`、`Transfer-Encoding`、`Keep-Alive`、`Proxy-Authenticate`、`Proxy-Authorization`、`TE`、`Trailer`、`Upgrade`
|
||||
- **THEN** SHALL 保留 `Content-Type` 等普通响应 header
|
||||
|
||||
### Requirement: 前端提取并处理错误码
|
||||
|
||||
前端 SHALL 提取后端结构化错误响应中的错误码并用于错误处理。
|
||||
@@ -212,7 +276,7 @@
|
||||
|
||||
#### Scenario: 请求体 JSON 格式错误
|
||||
|
||||
- **WHEN** 代理请求的请求体不是有效的 JSON 格式
|
||||
- **WHEN** 代理请求的请求体不是有效的 JSON 格式，且该接口需要网关解析请求体
|
||||
- **THEN** SHALL 返回 HTTP 400 Bad Request
|
||||
- **THEN** SHALL 返回以下 JSON 格式：
|
||||
```json
|
||||
|
||||
@@ -2,33 +2,66 @@
|
||||
|
||||
## Purpose
|
||||
|
||||
定义 OpenAI Chat Completions API 端点的协议代理行为，包括请求处理流程、模型路由、同协议透传和跨协议转换。
|
||||
定义 OpenAI Chat Completions API 端点及扩展层端点的协议代理行为，包括请求处理流程、模型路由、同协议透传和跨协议转换。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 支持 OpenAI 扩展层 v1 端点
|
||||
|
||||
网关 SHALL 提供带 `/v1` 层级的 OpenAI 扩展层端点供外部应用调用。
|
||||
|
||||
#### Scenario: Models 列表端点
|
||||
|
||||
- **WHEN** 应用发送 GET 请求到 `/openai/v1/models`
|
||||
- **THEN** 网关 SHALL 将剥离 `/openai` 后的 `/v1/models` 作为 OpenAI nativePath
|
||||
- **THEN** 网关 SHALL 返回 OpenAI Models 格式响应
|
||||
|
||||
#### Scenario: ModelInfo 详情端点
|
||||
|
||||
- **WHEN** 应用发送 GET 请求到 `/openai/v1/models/{provider_id}/{model_name}`
|
||||
- **THEN** 网关 SHALL 将剥离 `/openai` 后的 `/v1/models/{provider_id}/{model_name}` 作为 OpenAI nativePath
|
||||
- **THEN** 网关 SHALL 返回 OpenAI ModelInfo 格式响应
|
||||
|
||||
#### Scenario: Embeddings 端点
|
||||
|
||||
- **WHEN** 应用发送 POST 请求到 `/openai/v1/embeddings`
|
||||
- **THEN** 网关 SHALL 将剥离 `/openai` 后的 `/v1/embeddings` 作为 OpenAI nativePath
|
||||
- **THEN** 网关 SHALL 使用 OpenAI adapter 识别并处理 Embeddings 请求
|
||||
|
||||
#### Scenario: Rerank 端点
|
||||
|
||||
- **WHEN** 应用发送 POST 请求到 `/openai/v1/rerank`
|
||||
- **THEN** 网关 SHALL 将剥离 `/openai` 后的 `/v1/rerank` 作为 OpenAI nativePath
|
||||
- **THEN** 网关 SHALL 使用 OpenAI adapter 识别并处理 Rerank 请求
|
||||
|
||||
### Requirement: 支持 OpenAI Chat Completions API 端点
|
||||
|
||||
网关 SHALL 提供 OpenAI Chat Completions API 端点供外部应用调用。
|
||||
网关 SHALL 提供带 `/v1` 层级的 OpenAI Chat Completions API 端点供外部应用调用。
|
||||
|
||||
#### Scenario: 成功的非流式请求
|
||||
|
||||
- **WHEN** 应用发送 POST 请求到 `/openai/chat/completions`，携带有效的 OpenAI 请求格式（非流式）
|
||||
- **WHEN** 应用发送 POST 请求到 `/openai/v1/chat/completions`，携带有效的 OpenAI 请求格式（非流式）
|
||||
- **THEN** 网关 SHALL 剥离 `/openai` 前缀并将 `/v1/chat/completions` 作为 OpenAI nativePath
|
||||
- **THEN** 网关 SHALL 通过 ConversionEngine 转换请求
|
||||
- **THEN** 网关 SHALL 将转换后的请求转发到配置的供应商
|
||||
- **THEN** 网关 SHALL 将供应商的响应通过 ConversionEngine 转换为 OpenAI 格式返回给应用
|
||||
- **THEN** 若上游返回 2xx，网关 SHALL 将供应商的响应通过 ConversionEngine 转换为 OpenAI 格式返回给应用
|
||||
|
||||
#### Scenario: 成功的流式请求
|
||||
|
||||
- **WHEN** 应用发送 POST 请求到 `/openai/chat/completions`，携带 `stream: true`
|
||||
- **THEN** 网关 SHALL 通过 ConversionEngine 创建 StreamConverter
|
||||
- **WHEN** 应用发送 POST 请求到 `/openai/v1/chat/completions`，携带 `stream: true`
|
||||
- **THEN** 网关 SHALL 剥离 `/openai` 前缀并将 `/v1/chat/completions` 作为 OpenAI nativePath
|
||||
- **THEN** 网关 SHALL 通过 ConversionEngine 创建 StreamConverter 或使用同协议流式透传路径
|
||||
- **THEN** 网关 SHALL 使用 SSE 格式将转换后的响应流式返回给应用
|
||||
- **THEN** 网关 SHALL 在流完成时发送 `data: [DONE]`
|
||||
- **THEN** 网关 SHALL 在 OpenAI 协议流完成时发送或透传 `data: [DONE]`
|
||||
|
||||
#### Scenario: 同协议透传（OpenAI → OpenAI Provider）
|
||||
|
||||
- **WHEN** 客户端使用 OpenAI 协议且目标供应商也是 OpenAI 协议
|
||||
- **THEN** 网关 SHALL 跳过 Canonical 转换，仅重建认证 Header 后原样转发
|
||||
- **THEN** 请求和响应 Body SHALL 保持原样
|
||||
- **THEN** 网关 SHALL 跳过 Canonical 转换
|
||||
- **THEN** 网关 SHALL 使用 OpenAI adapter 重建上游 URL 和认证 Header
|
||||
- **THEN** 若请求使用统一模型 ID，网关 SHALL 仅通过 Smart Passthrough 改写 model 字段
|
||||
- **THEN** OpenAI adapter SHALL 将 `/v1/chat/completions` 映射为上游路径 `/chat/completions`
|
||||
- **THEN** OpenAI 供应商 `base_url` 配置到版本路径一级时，最终上游 URL SHALL 不重复 `/v1`
|
||||
|
||||
### Requirement: 根据模型名称路由请求
|
||||
|
||||
@@ -36,20 +69,25 @@
|
||||
|
||||
#### Scenario: 有效模型路由
|
||||
|
||||
- **WHEN** 请求包含存在于配置模型中的 `model` 字段
|
||||
- **AND** 该模型已启用
|
||||
- **WHEN** 请求包含有效统一模型 ID 格式的 `model` 字段
|
||||
- **AND** 该模型存在且已启用
|
||||
- **THEN** 网关 SHALL 将请求路由到该模型关联的供应商
|
||||
- **THEN** 网关 SHALL 从供应商的 `protocol` 字段获取 providerProtocol
|
||||
|
||||
#### Scenario: 模型未找到
|
||||
|
||||
- **WHEN** 请求包含不存在于配置模型中的 `model` 字段
|
||||
- **THEN** 网关 SHALL 使用 OpenAI 格式返回错误响应
|
||||
- **WHEN** 请求包含有效统一模型 ID 格式的 `model` 字段但模型不存在
|
||||
- **THEN** 网关 SHALL 使用应用统一错误格式返回 404 错误
|
||||
|
||||
#### Scenario: 模型已禁用
|
||||
|
||||
- **WHEN** 请求包含已禁用模型的 `model` 字段
|
||||
- **THEN** 网关 SHALL 使用 OpenAI 格式返回错误响应
|
||||
- **WHEN** 请求包含已禁用模型的有效统一模型 ID
|
||||
- **THEN** 网关 SHALL 使用应用统一错误格式返回 404 错误
|
||||
|
||||
#### Scenario: 原始模型名兼容透传
|
||||
|
||||
- **WHEN** 请求中的 `model` 字段不是有效统一模型 ID 格式
|
||||
- **THEN** 网关 SHALL 按无可路由 model 请求走 forwardPassthrough
|
||||
|
||||
### Requirement: 跨协议请求转换
|
||||
|
||||
@@ -60,8 +98,16 @@
|
||||
- **WHEN** 网关收到 OpenAI 协议请求且目标供应商使用不同协议
|
||||
- **THEN** 网关 SHALL 通过 ConversionEngine 将请求转换为目标协议格式
|
||||
- **THEN** 网关 SHALL 使用目标协议的 Adapter 构建 URL 和 Header
|
||||
- **THEN** 目标协议 Adapter SHALL 基于接口类型构建目标协议路径，不直接复用 OpenAI nativePath 中的 `/v1` 版本段
|
||||
|
||||
#### Scenario: 扩展层接口代理
|
||||
|
||||
- **WHEN** 网关收到 `/openai/v1/models` 等 GET 请求
|
||||
- **THEN** 网关 SHALL 通过 ConversionEngine 转换扩展层接口的响应格式
|
||||
- **THEN** 网关 SHALL 将 `/v1/models` 作为 OpenAI nativePath 识别扩展层接口
|
||||
- **THEN** 网关 SHALL 通过本地聚合或 ConversionEngine 转换扩展层接口响应格式
|
||||
|
||||
#### Scenario: 上游错误透传
|
||||
|
||||
- **WHEN** OpenAI 代理请求收到上游非 2xx HTTP 响应
|
||||
- **THEN** 网关 SHALL 直接透传上游 status code、过滤后的 headers 和 body
|
||||
- **THEN** 网关 SHALL NOT 将上游错误转换为 OpenAI 错误格式
|
||||
|
||||
@@ -11,7 +11,8 @@
|
||||
- `protocolName()` SHALL 返回 `"openai"`
|
||||
- `supportsPassthrough()` SHALL 返回 true
|
||||
- `buildHeaders(provider)` SHALL 构建 `Authorization: Bearer <api_key>` 和 `Content-Type: application/json`
|
||||
- `buildUrl(nativePath, interfaceType)` SHALL 按接口类型映射 URL 路径，不带 `/v1` 前缀
|
||||
- `detectInterfaceType(nativePath)` SHALL 识别带 `/v1` 前缀的 OpenAI nativePath
|
||||
- `buildUrl(nativePath, interfaceType)` SHALL 按接口类型映射上游 URL 路径，输出路径不带 `/v1` 前缀
|
||||
- `supportsInterface()` SHALL 对 CHAT、MODELS、MODEL_INFO、EMBEDDINGS、RERANK 返回 true
|
||||
|
||||
#### Scenario: 认证 Header 构建
|
||||
@@ -24,12 +25,34 @@
|
||||
|
||||
#### Scenario: URL 映射
|
||||
|
||||
- **WHEN** interfaceType == CHAT
|
||||
- **WHEN** interfaceType == CHAT 且 nativePath 为 `/v1/chat/completions`
|
||||
- **THEN** SHALL 映射为 `/chat/completions`
|
||||
- **WHEN** interfaceType == MODELS
|
||||
- **WHEN** interfaceType == MODELS 且 nativePath 为 `/v1/models`
|
||||
- **THEN** SHALL 映射为 `/models`
|
||||
- **WHEN** interfaceType == EMBEDDINGS
|
||||
- **WHEN** interfaceType == MODEL_INFO 且 nativePath 为 `/v1/models/{id}`
|
||||
- **THEN** SHALL 映射为 `/models/{id}`
|
||||
- **WHEN** interfaceType == EMBEDDINGS 且 nativePath 为 `/v1/embeddings`
|
||||
- **THEN** SHALL 映射为 `/embeddings`
|
||||
- **WHEN** interfaceType == RERANK 且 nativePath 为 `/v1/rerank`
|
||||
- **THEN** SHALL 映射为 `/rerank`
|
||||
|
||||
#### Scenario: 接口类型识别
|
||||
|
||||
- **WHEN** 调用 `DetectInterfaceType("/v1/chat/completions")`
|
||||
- **THEN** SHALL 返回 `InterfaceTypeChat`
|
||||
- **WHEN** 调用 `DetectInterfaceType("/v1/models")`
|
||||
- **THEN** SHALL 返回 `InterfaceTypeModels`
|
||||
- **WHEN** 调用 `DetectInterfaceType("/v1/embeddings")`
|
||||
- **THEN** SHALL 返回 `InterfaceTypeEmbeddings`
|
||||
- **WHEN** 调用 `DetectInterfaceType("/v1/rerank")`
|
||||
- **THEN** SHALL 返回 `InterfaceTypeRerank`
|
||||
|
||||
#### Scenario: 旧无版本路径不再作为已适配接口
|
||||
|
||||
- **WHEN** 调用 `DetectInterfaceType("/chat/completions")`
|
||||
- **THEN** SHALL 返回 `InterfaceTypePassthrough`
|
||||
- **WHEN** 调用 `DetectInterfaceType("/models")`
|
||||
- **THEN** SHALL 返回 `InterfaceTypePassthrough`
|
||||
|
||||
### Requirement: OpenAI 请求解码（OpenAI → Canonical）
|
||||
|
||||
@@ -272,40 +295,40 @@ Encoder SHALL 维护状态：
|
||||
- **THEN** SHALL 使用 CanonicalRerankRequest/Response 做字段映射
|
||||
### Requirement: 模型详情路径识别
|
||||
|
||||
OpenAI 适配器 SHALL 正确识别包含统一模型 ID 的模型详情路径。
|
||||
OpenAI 适配器 SHALL 正确识别包含统一模型 ID 的带 `/v1` 模型详情路径。
|
||||
|
||||
#### Scenario: 含斜杠的统一模型 ID 路径
|
||||
|
||||
- **WHEN** 路径为 `/models/openai/gpt-4`
|
||||
- **WHEN** 路径为 `/v1/models/openai/gpt-4`
|
||||
- **THEN** `DetectInterfaceType` SHALL 返回 `InterfaceTypeModelInfo`
|
||||
|
||||
#### Scenario: 含多段斜杠的统一模型 ID 路径
|
||||
|
||||
- **WHEN** 路径为 `/models/azure/accounts/org-123/models/gpt-4`
|
||||
- **WHEN** 路径为 `/v1/models/azure/accounts/org-123/models/gpt-4`
|
||||
- **THEN** `DetectInterfaceType` SHALL 返回 `InterfaceTypeModelInfo`
|
||||
|
||||
#### Scenario: 模型列表路径不受影响
|
||||
|
||||
- **WHEN** 路径为 `/models`
|
||||
- **WHEN** 路径为 `/v1/models`
|
||||
- **THEN** `DetectInterfaceType` SHALL 返回 `InterfaceTypeModels`
|
||||
|
||||
### Requirement: 提取统一模型 ID
|
||||
|
||||
OpenAI 适配器 SHALL 从路径中提取统一模型 ID。
|
||||
OpenAI 适配器 SHALL 从带 `/v1` 的模型详情路径中提取统一模型 ID。
|
||||
|
||||
#### Scenario: 标准路径提取
|
||||
|
||||
- **WHEN** 调用 `ExtractUnifiedModelID("/models/openai/gpt-4")`
|
||||
- **WHEN** 调用 `ExtractUnifiedModelID("/v1/models/openai/gpt-4")`
|
||||
- **THEN** SHALL 返回 `"openai/gpt-4"`
|
||||
|
||||
#### Scenario: 复杂路径提取
|
||||
|
||||
- **WHEN** 调用 `ExtractUnifiedModelID("/models/azure/accounts/org/models/gpt-4")`
|
||||
- **WHEN** 调用 `ExtractUnifiedModelID("/v1/models/azure/accounts/org/models/gpt-4")`
|
||||
- **THEN** SHALL 返回 `"azure/accounts/org/models/gpt-4"`
|
||||
|
||||
#### Scenario: 非模型详情路径
|
||||
|
||||
- **WHEN** 调用 `ExtractUnifiedModelID("/models")`
|
||||
- **WHEN** 调用 `ExtractUnifiedModelID("/v1/models")`
|
||||
- **THEN** SHALL 返回错误
|
||||
|
||||
### Requirement: 从请求体提取 model
|
||||
|
||||
@@ -6,6 +6,23 @@
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 代理路由入口一致
|
||||
|
||||
server 和 desktop 运行模式 SHALL 使用一致的代理路由入口，确保外部应用在不同运行模式下使用相同的协议 URL。
|
||||
|
||||
#### Scenario: server 代理路由
|
||||
|
||||
- **WHEN** server 模式启动 HTTP 路由
|
||||
- **THEN** SHALL 注册 `/{protocol}/*path` 形式的代理路由
|
||||
- **THEN** `/openai/v1/chat/completions` SHALL 进入 ProxyHandler 并提取 clientProtocol 为 `openai`
|
||||
|
||||
#### Scenario: desktop 代理路由
|
||||
|
||||
- **WHEN** desktop 模式启动 HTTP 路由
|
||||
- **THEN** SHALL 注册显式 `/openai/*path` 和 `/anthropic/*path` 代理路由
|
||||
- **THEN** SHALL 在进入 ProxyHandler 前设置 clientProtocol 参数
|
||||
- **THEN** `/openai/v1/chat/completions` SHALL 进入 ProxyHandler 并提取 clientProtocol 为 `openai`
|
||||
|
||||
### Requirement: 实现统一代理 Handler
|
||||
|
||||
系统 SHALL 实现统一的 ProxyHandler，替代现有的 OpenAIHandler 和 AnthropicHandler。
|
||||
@@ -16,13 +33,28 @@ ProxyHandler SHALL 依赖 ConversionEngine、ProviderClient、RoutingService、S
|
||||
|
||||
- **WHEN** 收到 `/{protocol}/{path}` 格式的请求
|
||||
- **THEN** SHALL 从 URL 第一段提取 protocol 作为 clientProtocol
|
||||
- **THEN** SHALL 剥离前缀得到 nativePath
|
||||
- **THEN** nativePath SHALL 不添加任何前缀，直接使用 path 参数
|
||||
- **THEN** SHALL 只剥离第一段协议前缀得到 nativePath
|
||||
- **THEN** nativePath SHALL 不添加任何前缀，也不移除协议内部版本段，直接使用 path 参数
|
||||
|
||||
#### Scenario: OpenAI v1 nativePath 保留
|
||||
|
||||
- **WHEN** 收到 `/openai/v1/chat/completions` 请求
|
||||
- **THEN** SHALL 从 URL 第一段提取 `openai` 作为 clientProtocol
|
||||
- **THEN** SHALL 剥离 `/openai` 后得到 nativePath `/v1/chat/completions`
|
||||
- **THEN** SHALL 将 `/v1/chat/completions` 交给 OpenAI adapter 识别
|
||||
|
||||
#### Scenario: Anthropic v1 nativePath 保留
|
||||
|
||||
- **WHEN** 收到 `/anthropic/v1/messages` 请求
|
||||
- **THEN** SHALL 从 URL 第一段提取 `anthropic` 作为 clientProtocol
|
||||
- **THEN** SHALL 剥离 `/anthropic` 后得到 nativePath `/v1/messages`
|
||||
- **THEN** SHALL 将 `/v1/messages` 交给 Anthropic adapter 识别
|
||||
|
||||
#### Scenario: 协议前缀必须是已注册协议
|
||||
|
||||
- **WHEN** 收到的 URL 前缀不是已注册的协议名称
|
||||
- **THEN** SHALL 返回 404 错误
|
||||
- **THEN** 错误响应 SHALL 使用应用统一错误格式
|
||||
|
||||
#### Scenario: 接口类型识别
|
||||
|
||||
@@ -37,131 +69,157 @@ ProxyHandler SHALL 按以下流程处理非流式请求。
|
||||
#### Scenario: 完整转换流程
|
||||
|
||||
- **WHEN** 收到非流式请求
|
||||
- **THEN** SHALL 解析请求体为 JSON
|
||||
- **THEN** SHALL 调用 RoutingService.Route(modelName) 获取路由结果
|
||||
- **THEN** SHALL 通过客户端 adapter 明确支持的接口规则提取 model
|
||||
- **THEN** SHALL 调用 RoutingService.RouteByModelName(providerID, modelName) 获取路由结果
|
||||
- **THEN** SHALL 从路由结果的 Provider.Protocol 获取 providerProtocol
|
||||
- **THEN** SHALL 构建 TargetProvider（base_url, api_key, model_name, adapter_config）
|
||||
- **THEN** SHALL 调用 engine.convertHttpRequest(body, clientProtocol, providerProtocol, provider)
|
||||
- **THEN** SHALL 调用 engine.convertHttpRequest 获取 HTTPRequestSpec
|
||||
- **THEN** SHALL 调用 providerClient.Send(ctx, requestSpec)
|
||||
- **THEN** SHALL 调用 engine.convertHttpResponse(response, clientProtocol, providerProtocol, interfaceType)
|
||||
- **THEN** 若上游响应状态码为 2xx，SHALL 调用 engine.convertHttpResponse 转换响应
|
||||
- **THEN** SHALL 将转换后的响应返回给客户端
|
||||
|
||||
#### Scenario: 路由失败处理
|
||||
|
||||
- **WHEN** RoutingService.Route 返回错误
|
||||
- **THEN** SHALL 使用 clientProtocol 对应的 Adapter.encodeError 编码错误响应
|
||||
- **WHEN** RoutingService.RouteByModelName 返回错误
|
||||
- **THEN** SHALL 使用应用统一错误格式返回网关层错误
|
||||
- **THEN** SHALL 返回适当的 HTTP 状态码
|
||||
|
||||
#### Scenario: 上游请求失败处理
|
||||
|
||||
- **WHEN** ProviderClient.Send 返回错误
|
||||
- **THEN** SHALL 使用 clientProtocol 对应的 Adapter.encodeError 编码错误响应
|
||||
- **THEN** SHALL 包装原始错误信息
|
||||
- **WHEN** ProviderClient.Send 未收到上游 HTTP 响应并返回错误
|
||||
- **THEN** SHALL 使用应用统一错误格式返回网关层错误
|
||||
- **THEN** SHALL 包装原始错误信息用于日志
|
||||
|
||||
#### Scenario: 上游非 2xx 响应透传
|
||||
|
||||
- **WHEN** ProviderClient.Send 收到上游 HTTP 响应且状态码不是 2xx
|
||||
- **THEN** ProxyHandler SHALL NOT 调用 engine.convertHttpResponse
|
||||
- **THEN** SHALL 透传上游 status code
|
||||
- **THEN** SHALL 透传过滤 hop-by-hop header 后的上游 headers
|
||||
- **THEN** SHALL 透传上游 body
|
||||
|
||||
### Requirement: 流式请求处理流程
|
||||
|
||||
ProxyHandler SHALL 按以下流程处理流式请求。
|
||||
|
||||
#### Scenario: 流式转换流程
|
||||
#### Scenario: 跨协议流式转换流程
|
||||
|
||||
- **WHEN** 请求中 stream=true 或接口类型为 CHAT 且请求体含 stream:true
|
||||
- **WHEN** 请求中 stream=true 且 clientProtocol != providerProtocol
|
||||
- **THEN** SHALL 执行与非流式相同的前置处理（路由、构建 TargetProvider）
|
||||
- **THEN** SHALL 调用 engine.convertHttpRequest 获取 HTTPRequestSpec
|
||||
- **THEN** SHALL 调用 providerClient.SendStream(ctx, requestSpec) 获取流
|
||||
- **THEN** SHALL 调用 engine.createStreamConverter(clientProtocol, providerProtocol, provider)
|
||||
- **THEN** 若上游返回 2xx 流式响应，SHALL 调用 engine.createStreamConverter(clientProtocol, providerProtocol, provider)
|
||||
- **THEN** SHALL 设置响应 Header `Content-Type: text/event-stream`
|
||||
- **THEN** SHALL 对每个流 chunk 调用 converter.processChunk 并写入响应
|
||||
- **THEN** SHALL 在流结束时调用 converter.flush() 刷新缓冲
|
||||
|
||||
#### Scenario: 同协议透传流式
|
||||
#### Scenario: 同协议 raw 流式透传
|
||||
|
||||
- **WHEN** clientProtocol == providerProtocol
|
||||
- **WHEN** clientProtocol == providerProtocol 且响应不需要 model 改写
|
||||
- **THEN** SHALL 直接将上游 SSE 字节流写入响应
|
||||
- **THEN** SHALL 保留 SSE frame 边界和结束标记
|
||||
- **THEN** SHALL NOT 做任何解析或转换
|
||||
|
||||
#### Scenario: 同协议流式 Smart Passthrough
|
||||
|
||||
- **WHEN** clientProtocol == providerProtocol 且响应需要 model 改写
|
||||
- **THEN** SHALL 按 SSE frame 读取上游流
|
||||
- **THEN** SHALL 仅改写 `data` JSON payload 内的 model 字段
|
||||
- **THEN** SHALL 原样保留 `[DONE]` 结束标记
|
||||
- **THEN** SHALL 重建合法 SSE frame 写回客户端
|
||||
- **THEN** SHALL NOT 做 Canonical decode/encode 转换
|
||||
|
||||
#### Scenario: 流式上游非 2xx 响应透传
|
||||
|
||||
- **WHEN** 流式请求收到上游非 2xx HTTP 响应
|
||||
- **THEN** SHALL NOT 创建 StreamConverter
|
||||
- **THEN** SHALL 透传上游 status code、过滤后的 headers 和 body
|
||||
|
||||
#### Scenario: 流式错误处理
|
||||
|
||||
- **WHEN** 流过程中发生错误
|
||||
- **WHEN** 流过程中发生网关层读取或写入错误
|
||||
- **THEN** SHALL 记录错误日志
|
||||
- **THEN** SHALL 关闭响应流
|
||||
|
||||
### Requirement: 统计记录
|
||||
|
||||
ProxyHandler SHALL 记录请求统计。
|
||||
|
||||
#### Scenario: 异步记录统计
|
||||
|
||||
- **WHEN** 请求处理完成（成功或失败）
|
||||
- **THEN** SHALL 异步调用 StatsService.Record
|
||||
- **THEN** SHALL NOT 阻塞响应返回
|
||||
|
||||
### Requirement: GET 请求透传
|
||||
|
||||
ProxyHandler SHALL 支持 GET 请求的扩展层接口代理。
|
||||
ProxyHandler SHALL 支持无请求体 GET 请求和未知接口透传。
|
||||
|
||||
#### Scenario: Models 接口<EFBFBD><EFBFBD>理
|
||||
#### Scenario: Models 接口本地处理
|
||||
|
||||
- **WHEN** 收到客户端协议的模型列表路径请求，例如 `GET /openai/v1/models` 或 `GET /anthropic/v1/models`
|
||||
- **THEN** SHALL 走模型列表本地聚合流程
|
||||
- **THEN** SHALL NOT 请求上游供应商
|
||||
|
||||
#### Scenario: 未知 GET 接口透传
|
||||
|
||||
- **WHEN** 收到未被 adapter 识别为本地处理接口的 GET 请求
|
||||
- **THEN** SHALL 走 forwardPassthrough 透传到上游供应商
|
||||
- **THEN** SHALL 保留原始 query string
|
||||
|
||||
- **WHEN** 收到 GET /{protocol}/v1/models 请求
|
||||
- **THEN** SHALL 执行路由和协议识别
|
||||
- **THEN** SHALL 调用 engine.convertHttpRequest（GET 请求 body 为空）
|
||||
- **THEN** SHALL 调用 providerClient.Send 发送请求
|
||||
- **THEN** SHALL 调用 engine.convertHttpResponse 转换响应格式
|
||||
- **THEN** SHALL 返回转换后的响应
|
||||
### Requirement: 代理请求路由
|
||||
|
||||
ProxyHandler SHALL 使用统一模型 ID 路由所有代理请求。
|
||||
ProxyHandler SHALL 使用统一模型 ID 路由 adapter 明确支持提取 model 的代理请求。
|
||||
|
||||
#### Scenario: 提取统一模型 ID
|
||||
|
||||
- **WHEN** 收到 Chat、Embeddings 或 Rerank 接口的 POST 请求（含请求体）
|
||||
- **WHEN** 收到 adapter 明确支持提取 model 的接口请求（如 Chat、Embeddings 或 Rerank）且请求体非空
|
||||
- **THEN** SHALL 调用客户端协议 adapter 的 `ExtractModelName(body, ifaceType)` 提取 model 值
|
||||
- **THEN** SHALL 调用 `ParseUnifiedModelID` 解析得到 providerID 和 modelName
|
||||
- **THEN** SHALL 调用 `RoutingService.RouteByModelName(providerID, modelName)` 路由
|
||||
|
||||
#### Scenario: 未知接口不猜测 model
|
||||
|
||||
- **WHEN** 收到 adapter 未明确支持提取 model 的接口请求
|
||||
- **THEN** ProxyHandler SHALL NOT 尝试通用解析顶层 model 字段
|
||||
- **THEN** SHALL 按无 model 请求走 forwardPassthrough
|
||||
|
||||
#### Scenario: GET 请求或无请求体
|
||||
|
||||
- **WHEN** 收到 GET 请求或请求体为空或请求体中无法提取 model 字段
|
||||
- **THEN** SHALL 走 forwardPassthrough 透传到上游供应商（兼容未适配的客户端和无 body 请求）
|
||||
- **THEN** SHALL 走 forwardPassthrough 透传到上游供应商
|
||||
|
||||
#### Scenario: 无效的统一模型 ID
|
||||
|
||||
- **WHEN** 请求体中 `model` 字段不是有效的统一模型 ID 格式（不含 `/`）
|
||||
- **THEN** SHALL 走 forwardPassthrough 透传到上游供应商（兼容使用原始模型名的客户端）
|
||||
- **WHEN** adapter 已提取 model 字段但该字段不是有效的统一模型 ID 格式（不含 `/`）
|
||||
- **THEN** SHALL 走 forwardPassthrough 透传到上游供应商
|
||||
|
||||
#### Scenario: 模型不存在
|
||||
|
||||
- **WHEN** 解析统一模型 ID 后，数据库中找不到对应的 provider_id + model_name 组合
|
||||
- **THEN** SHALL 返回错误响应，状态码为 404
|
||||
- **THEN** SHALL 返回应用统一错误响应，状态码为 404
|
||||
|
||||
#### Scenario: 模型已禁用
|
||||
|
||||
- **WHEN** 解析统一模型 ID 后，对应的模型 enabled 为 false
|
||||
- **THEN** SHALL 返回错误响应，状态码为 404
|
||||
- **THEN** SHALL 返回应用统一错误响应，状态码为 404
|
||||
|
||||
#### Scenario: 供应商已禁用
|
||||
|
||||
- **WHEN** 解析统一模型 ID 后，对应的供应商 enabled 为 false
|
||||
- **THEN** SHALL 返回错误响应，状态码为 404
|
||||
- **THEN** SHALL 返回应用统一错误响应，状态码为 404
|
||||
|
||||
### Requirement: 同协议 Smart Passthrough
|
||||
|
||||
当客户端协议与供应商协议相同时，ProxyHandler SHALL 使用 Smart Passthrough 处理 Chat、Embedding、Rerank 请求。
|
||||
当客户端协议与供应商协议相同时，ProxyHandler SHALL 使用 Smart Passthrough 处理 adapter 明确支持的 Chat、Embedding、Rerank 请求。
|
||||
|
||||
#### Scenario: 同协议非流式请求
|
||||
|
||||
- **WHEN** 客户端协议 == 供应商协议，且为非流式请求
|
||||
- **THEN** SHALL 调用 adapter 的 `RewriteRequestModelName(body, modelName, ifaceType)` 将请求体中 model 从统一 ID 改写为上游模型名
|
||||
- **THEN** SHALL 构建 URL 和 Headers（同当前透传逻辑）
|
||||
- **THEN** SHALL 使用 providerAdapter.BuildUrl(nativePath, ifaceType) 构建上游 URL 路径
|
||||
- **THEN** SHALL 使用 providerAdapter.BuildHeaders(provider) 构建 Headers
|
||||
- **THEN** SHALL 发送改写后的请求体到上游
|
||||
- **THEN** SHALL 调用 adapter 的 `RewriteResponseModelName(resp.Body, unifiedModelID, ifaceType)` 将响应中 model 从上游名改写为统一 ID
|
||||
- **THEN** SHALL NOT 对 body 做全量 decode → encode，保持未改写字段的原始 bytes
|
||||
- **THEN** 若上游返回 2xx，SHALL 调用 adapter 的 `RewriteResponseModelName(resp.Body, unifiedModelID, ifaceType)` 将响应中 model 从上游名改写为统一 ID
|
||||
- **THEN** SHALL NOT 对 body 做 Canonical 全量 decode → encode，保持未改写字段的 JSON 内容和类型不变，但不承诺保留原始字节顺序或空白
|
||||
|
||||
#### Scenario: 同协议流式请求
|
||||
|
||||
- **WHEN** 客户端协议 == 供应商协议，且为流式请求
|
||||
- **THEN** SHALL 对请求体做 `RewriteRequestModelName` 改写 model 字段
|
||||
- **THEN** SHALL 逐 SSE chunk 调用 `RewriteResponseModelName` 改写响应中 model 字段
|
||||
- **THEN** SHALL NOT 对 chunk 做全量 decode → encode
|
||||
- **THEN** SHALL 使用 providerAdapter.BuildUrl(nativePath, ifaceType) 构建上游 URL 路径
|
||||
- **THEN** SHALL 按 raw passthrough 或 SSE frame 级 Smart Passthrough 处理响应流
|
||||
- **THEN** SHALL NOT 对 chunk 做 Canonical 全量 decode → encode
|
||||
|
||||
#### Scenario: Smart Passthrough 保真性
|
||||
|
||||
@@ -196,6 +254,21 @@ ProxyHandler SHALL 从数据库聚合返回模型列表，不再透传上游。
|
||||
- **THEN** SHALL 使用客户端协议的 adapter 编码响应
|
||||
- **THEN** SHALL NOT 请求上游供应商
|
||||
|
||||
#### Scenario: OpenAI Models 本地聚合
|
||||
|
||||
- **WHEN** 收到 `GET /openai/v1/models` 请求
|
||||
- **THEN** nativePath SHALL 为 `/v1/models`
|
||||
- **THEN** OpenAI adapter SHALL 将接口类型识别为 `InterfaceTypeModels`
|
||||
- **THEN** ProxyHandler SHALL 从数据库聚合返回 OpenAI Models 格式响应
|
||||
|
||||
#### Scenario: 客户端协议模型列表路径
|
||||
|
||||
- **WHEN** 收到客户端协议的模型列表路径请求，例如 `GET /openai/v1/models` 或 `GET /anthropic/v1/models`
|
||||
- **THEN** SHALL 从数据库查询所有 enabled 的模型（关联 enabled 的供应商）
|
||||
- **THEN** SHALL 组装 `CanonicalModelList`，每个模型的 ID 字段为统一模型 ID（`provider_id/model_name`），Name 字段为 model_name，OwnedBy 字段为 provider_id
|
||||
- **THEN** SHALL 使用客户端协议的 adapter 编码响应
|
||||
- **THEN** SHALL NOT 请求上游供应商
|
||||
|
||||
#### Scenario: 无可用模型
|
||||
|
||||
- **WHEN** 数据库中没有 enabled 的模型
|
||||
@@ -215,10 +288,27 @@ ProxyHandler SHALL 从数据库查询返回模型详情，不再透传上游。
|
||||
- **THEN** SHALL 使用客户端协议的 adapter 编码响应
|
||||
- **THEN** SHALL NOT 请求上游供应商
|
||||
|
||||
#### Scenario: OpenAI ModelInfo 本地查询
|
||||
|
||||
- **WHEN** 收到 `GET /openai/v1/models/openai/gpt-4` 请求
|
||||
- **THEN** nativePath SHALL 为 `/v1/models/openai/gpt-4`
|
||||
- **THEN** OpenAI adapter SHALL 提取统一模型 ID `openai/gpt-4`
|
||||
- **THEN** ProxyHandler SHALL 从数据库查询模型详情并返回 OpenAI ModelInfo 格式响应
|
||||
|
||||
#### Scenario: 客户端协议模型详情路径
|
||||
|
||||
- **WHEN** 收到客户端协议的模型详情路径请求，例如 `GET /openai/v1/models/{provider_id}/{model_name}` 或 `GET /anthropic/v1/models/{provider_id}/{model_name}`
|
||||
- **THEN** SHALL 调用 adapter 的 `ExtractUnifiedModelID` 提取统一模型 ID
|
||||
- **THEN** SHALL 解析统一模型 ID 得到 providerID 和 modelName
|
||||
- **THEN** SHALL 从数据库查询对应的模型和供应商
|
||||
- **THEN** SHALL 组装 `CanonicalModelInfo`，ID 字段为统一模型 ID（`provider_id/model_name`），Name 字段为 model_name，OwnedBy 字段为 provider_id
|
||||
- **THEN** SHALL 使用客户端协议的 adapter 编码响应
|
||||
- **THEN** SHALL NOT 请求上游供应商
|
||||
|
||||
#### Scenario: 模型详情不存在
|
||||
|
||||
- **WHEN** 统一模型 ID 对应的模型不存在或已禁用
|
||||
- **THEN** SHALL 返回错误响应，状态码为 404
|
||||
- **THEN** SHALL 返回应用统一错误响应，状态码为 404
|
||||
|
||||
### Requirement: 统计记录
|
||||
|
||||
@@ -228,3 +318,4 @@ ProxyHandler SHALL 使用 providerID 和 modelName 记录使用统计。
|
||||
|
||||
- **WHEN** 代理请求成功完成
|
||||
- **THEN** SHALL 异步调用 `StatsService.Record(providerID, modelName)`
|
||||
- **THEN** SHALL NOT 阻塞响应返回
|
||||
|
||||
Reference in New Issue
Block a user