lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
38a2555c7b5772d7f783ab1bf237d65d54f6be27
nex/openspec/specs/openai-protocol-proxy/spec.md

5.2 KiB
Raw Blame History

OpenAI Protocol Proxy

Purpose

定义 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 提供带 /v1 层级的 OpenAI Chat Completions API 端点供外部应用调用。

Scenario: 成功的非流式请求

  • WHEN 应用发送 POST 请求到 /openai/v1/chat/completions，携带有效的 OpenAI 请求格式（非流式）
  • THEN 网关 SHALL 剥离 /openai 前缀并将 /v1/chat/completions 作为 OpenAI nativePath
  • THEN 网关 SHALL 通过 ConversionEngine 转换请求
  • THEN 网关 SHALL 将转换后的请求转发到配置的供应商
  • THEN 若上游返回 2xx，网关 SHALL 将供应商的响应通过 ConversionEngine 转换为 OpenAI 格式返回给应用

Scenario: 成功的流式请求

  • 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 在 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 字段
  • THEN OpenAI adapter SHALL 将 /v1/chat/completions 映射为上游路径 /chat/completions
  • THEN OpenAI 供应商 base_url 配置到版本路径一级时，最终上游 URL SHALL 不重复 /v1

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
  • THEN 目标协议 Adapter SHALL 基于接口类型构建目标协议路径，不直接复用 OpenAI nativePath 中的 /v1 版本段

Scenario: 扩展层接口代理

  • WHEN 网关收到 /openai/v1/models 等 GET 请求
  • THEN 网关 SHALL 将 /v1/models 作为 OpenAI nativePath 识别扩展层接口
  • THEN 网关 SHALL 通过本地聚合或 ConversionEngine 转换扩展层接口响应格式

Scenario: 上游错误透传

  • WHEN OpenAI 代理请求收到上游非 2xx HTTP 响应
  • THEN 网关 SHALL 直接透传上游 status code、过滤后的 headers 和 body
  • THEN 网关 SHALL NOT 将上游错误转换为 OpenAI 错误格式
View Git Blame Copy Permalink