lanyuanxiaoyao
915b004924
实现支持 OpenAI 和 Anthropic 双协议的统一大模型 API 网关 MVP 版本，包含： - OpenAI 和 Anthropic 协议代理 - 供应商和模型管理 - 用量统计 - 前端配置界面
130 lines
4.4 KiB
Markdown
130 lines
4.4 KiB
Markdown
# OpenAI 协议代理
|
||
|
||
## Purpose
|
||
|
||
TBD - 提供 OpenAI Chat Completions API 的代理功能
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 支持 OpenAI Chat Completions API 端点
|
||
|
||
网关 SHALL 提供 OpenAI Chat Completions API 端点 `POST /v1/chat/completions` 供外部应用调用。
|
||
|
||
#### Scenario: 成功的非流式请求
|
||
|
||
- **WHEN** 应用发送 POST 请求到 `/v1/chat/completions`，携带有效的 OpenAI 请求格式（非流式）
|
||
- **THEN** 网关 SHALL 将请求转发到配置的供应商
|
||
- **THEN** 网关 SHALL 将供应商的响应以 OpenAI 格式返回给应用
|
||
|
||
#### Scenario: 成功的流式请求
|
||
|
||
- **WHEN** 应用发送 POST 请求到 `/v1/chat/completions`，携带 `stream: true`
|
||
- **THEN** 网关 SHALL 将请求转发到配置的供应商
|
||
- **THEN** 网关 SHALL 使用 SSE 格式将响应流式返回给应用
|
||
- **THEN** 网关 SHALL 在流完成时发送 `data: [DONE]`
|
||
|
||
### Requirement: 支持 Function Calling
|
||
|
||
网关 SHALL 在非流式和流式模式下都支持 OpenAI Function Calling。
|
||
|
||
#### Scenario: 非流式函数调用
|
||
|
||
- **WHEN** 应用发送包含 `tools` 定义的请求
|
||
- **AND** 供应商返回包含 `tool_calls` 的响应
|
||
- **THEN** 网关 SHALL 在响应中原样转发 `tool_calls`
|
||
|
||
#### Scenario: 流式函数调用
|
||
|
||
- **WHEN** 应用发送包含 `tools` 定义的流式请求
|
||
- **AND** 供应商在 delta 块中流式返回 `tool_calls`
|
||
- **THEN** 网关 SHALL 将 `tool_calls` 块流式发送给应用
|
||
- **THEN** 网关 SHALL 在完成时设置 `finish_reason: "tool_calls"`
|
||
|
||
#### Scenario: 工具结果提交
|
||
|
||
- **WHEN** 应用发送包含 `role: "tool"` 消息的后续请求，携带函数结果
|
||
- **THEN** 网关 SHALL 将工具结果原样转发给供应商
|
||
|
||
### Requirement: 根据模型名称路由请求
|
||
|
||
网关 SHALL 根据请求中的 `model` 字段将请求路由到相应的供应商。
|
||
|
||
#### Scenario: 有效模型路由
|
||
|
||
- **WHEN** 请求包含存在于配置模型中的 `model` 字段
|
||
- **AND** 该模型已启用
|
||
- **THEN** 网关 SHALL 将请求路由到该模型关联的供应商
|
||
|
||
#### Scenario: 模型未找到
|
||
|
||
- **WHEN** 请求包含不存在于配置模型中的 `model` 字段
|
||
- **THEN** 网关 SHALL 返回带有适当错误消息的错误响应
|
||
|
||
#### Scenario: 模型已禁用
|
||
|
||
- **WHEN** 请求包含已禁用模型的 `model` 字段
|
||
- **THEN** 网关 SHALL 返回错误响应，指示模型不可用
|
||
|
||
### Requirement: 对 OpenAI 兼容供应商透明代理
|
||
|
||
网关 SHALL 对 OpenAI 兼容供应商的请求和响应进行透明转发，不做修改。
|
||
|
||
#### Scenario: 请求转发
|
||
|
||
- **WHEN** 网关收到 OpenAI 协议请求
|
||
- **AND** 目标供应商是 OpenAI 兼容的
|
||
- **THEN** 网关 SHALL 将请求体原样转发给供应商
|
||
- **THEN** 网关 SHALL 在 Authorization 头中设置供应商的 API Key
|
||
- **THEN** 网关 SHALL 使用供应商的 base URL
|
||
|
||
#### Scenario: 响应转发
|
||
|
||
- **WHEN** 供应商返回响应
|
||
- **THEN** 网关 SHALL 将响应体原样返回给应用
|
||
- **THEN** 网关 SHALL 保留所有响应头和状态码
|
||
|
||
### Requirement: 处理供应商错误
|
||
|
||
网关 SHALL 将供应商错误透明返回给应用。
|
||
|
||
#### Scenario: 供应商返回错误
|
||
|
||
- **WHEN** 供应商返回错误响应（4xx 或 5xx）
|
||
- **THEN** 网关 SHALL 将相同的错误响应返回给应用
|
||
- **THEN** 网关 SHALL 保留错误消息和状态码
|
||
|
||
#### Scenario: 供应商超时
|
||
|
||
- **WHEN** 供应商在超时时间内未响应
|
||
- **THEN** 网关 SHALL 向应用返回超时错误
|
||
|
||
#### Scenario: 供应商连接失败
|
||
|
||
- **WHEN** 网关无法连接到供应商
|
||
- **THEN** 网关 SHALL 向应用返回连接错误
|
||
|
||
### Requirement: 支持标准 OpenAI 请求字段
|
||
|
||
网关 SHALL 支持所有标准 OpenAI Chat Completions API 请求字段。
|
||
|
||
#### Scenario: 支持标准字段
|
||
|
||
- **WHEN** 请求包含标准字段（model, messages, temperature, max_tokens, top_p, frequency_penalty, presence_penalty, stop, n, stream, tools, tool_choice, user）
|
||
- **THEN** 网关 SHALL 接受并将所有字段转发给供应商
|
||
|
||
### Requirement: 维护流式连接稳定性
|
||
|
||
网关 SHALL 维护稳定的流式连接并优雅处理中断。
|
||
|
||
#### Scenario: 流中断
|
||
|
||
- **WHEN** 供应商流在传输过程中中断
|
||
- **THEN** 网关 SHALL 优雅关闭客户端连接
|
||
- **THEN** 网关 SHALL 记录中断日志以便调试
|
||
|
||
#### Scenario: 客户端提前断开
|
||
|
||
- **WHEN** 客户端在流完成前断开连接
|
||
- **THEN** 网关 SHALL 取消供应商请求
|
||
- **THEN** 网关 SHALL 释放相关资源
|