美化项目与AI网关文档

2026-07-16 12:47:57 +08:00
parent da7b29d2e3
commit 7002e42c06
2 changed files with 194 additions and 112 deletions
@@ -1,23 +1,33 @@
+<a id="top"></a>
+
+<div align="center">
+
+<img src="assets/logo.svg" width="88" alt="OCI Portal logo">
+
 # AI 网关

+**将多路 OCI Generative AI 统一为 OpenAI、Anthropic 与 xAI 兼容接口**
+
+![OpenAI](https://img.shields.io/badge/OpenAI-Responses%20%7C%20Chat-412991?logo=openai&logoColor=white)
+![Anthropic](https://img.shields.io/badge/Anthropic-Messages-D97757?logo=anthropic&logoColor=white)
+![xAI](https://img.shields.io/badge/xAI-TTS%20%7C%20Tools-111111?logo=x&logoColor=white)
+![Streaming](https://img.shields.io/badge/Streaming-SSE-0F9D58)
+
+[快速接入](#quick-start) · [端点一览](#endpoints) · [路由机制](#routing) · [Codex 接入](#codex) · [已知限制](#limitations) · [兼容矩阵](#compatibility)
+
+</div>
+
 > [!NOTE]
-> OCI Portal AI 网关将多个 OCI GenAI 渠道统一为 OpenAI、Anthropic 与 xAI
-> 兼容接口，并集中处理鉴权、模型访问控制、渠道调度和协议适配。
->
-> 路径、参数与响应结构以 [Swagger YAML](swagger.yaml) 或运行时 Swagger UI
-> 为准；协议差异、兼容改写和实测边界以本文为准。
+> 网关集中处理密钥鉴权、模型访问控制、渠道调度与协议适配。路径、参数和
+> 响应结构以 [Swagger YAML](swagger.yaml) 或运行时 Swagger UI 为准；协议差异、
+> 兼容改写和实测边界以本文为准。

-**兼容快照：2026-07-15**
-
-## 快速导航
-
- [快速接入](#quick-start)
- [端点一览](#endpoints)
- [路由与全局行为](#routing)
- [Codex 接入](#codex)
- [已知限制](#limitations)
- [字段兼容矩阵](#compatibility)
- [实现索引](#implementation)
+| 文档属性 | 当前值 |
+| --- | --- |
+| 兼容快照 | **2026-07-16** |
+| API 基址 | `/ai/v1` |
+| 首选对话协议 | OpenAI Responses |
+| 会话模式 | 无状态，客户端携带完整上下文 |

 <a id="quick-start"></a>

@@ -25,19 +35,13 @@

 ### 基础地址与鉴权

-```text
-Base URL: https://<网关地址>/ai/v1
-```
+网关密钥在管理面板中创建。连接信息如下：

-网关密钥在管理面板中创建，支持以下任一请求头：
-
-```http
-Authorization: Bearer sk-...
-```
-
-```http
-x-api-key: sk-...
-```
+| 项目 | 配置 |
+| --- | --- |
+| Base URL | `https://<网关地址>/ai/v1` |
+| Bearer 鉴权 | `Authorization: Bearer sk-...` |
+| API Key 鉴权 | `x-api-key: sk-...` |

 密钥可绑定渠道分组和模型白名单。全局模型黑名单会同时作用于模型列表、
 请求路由和探测候选；开启「过滤弃用模型」后，OCI 已宣布弃用的模型也会从
@@ -50,6 +54,15 @@ curl "https://<网关地址>/ai/v1/models" \
  -H "Authorization: Bearer $OCI_PORTAL_KEY"
 ```

+再发起一条最小 Responses 请求；请将示例模型替换为模型列表中的可见模型：
+
+```bash
+curl "https://<网关地址>/ai/v1/responses" \
+  -H "Authorization: Bearer $OCI_PORTAL_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"xai.grok-4.3","input":"你好，请用一句话介绍自己。"}'
+```
+
 <a id="endpoints"></a>

 ## 端点一览
@@ -66,12 +79,14 @@ curl "https://<网关地址>/ai/v1/models" \
 | 安全 | `POST /ai/v1/moderations` | OpenAI 外壳映射 OCI Guardrails | — |
 | 发现 | `GET /ai/v1/models` | 当前密钥可见模型列表 | — |

-选择建议：
+### 如何选择协议

- 新客户端优先使用 **Responses**
- Anthropic SDK 或 Claude 生态客户端使用 **Messages**
- 仅支持旧 OpenAI 对话协议的客户端使用 **Chat Completions**
- Embeddings、TTS、Rerank 与 Moderations 使用各自专用端点
+| 使用场景 | 推荐接口 |
+| --- | --- |
+| 新客户端、推理模型、服务端工具 | **Responses** |
+| Anthropic SDK、Claude 生态客户端 | **Messages** |
+| 仅支持旧 OpenAI 对话协议的客户端 | **Chat Completions** |
+| 向量、语音、重排与安全审核 | 对应专用端点 |

 <a id="routing"></a>

@@ -106,6 +121,14 @@ flowchart LR
 | 文件输入 | `input_file` 会被 OCI ZDR 形态拒绝，详见[已知限制](#limitations) |
 | Chat 定位 | Chat Completions 只承担协议转换与兼容修复；新能力优先落在 Responses 与 Messages |

+### 可配置运行策略
+
+| 策略 | 默认行为 | 配置入口 |
+| --- | --- | --- |
+| Responses 流式保险丝 | 开启；阈值 `60 KB`，按 `instructions` 与 `tools` 两个字段的原始 JSON 值计算 | **设置 → AI → 流式保险丝** |
+| Grok 服务端搜索 | 对 `xai.` 模型默认注入 `web_search` 与 `x_search`；同名工具不重复覆盖 | **设置 → AI → Grok 服务端搜索工具** |
+| 弃用模型过滤 | 开启后从模型列表、请求路由与探测候选中统一排除 | **设置 → AI → 模型治理** |
+
 <a id="codex"></a>

 ## Codex 接入
@@ -143,7 +166,7 @@ model = "xai.grok-4.3"
 ```

 > [!IMPORTANT]
-> `codex-cli 0.144.1` 已实测主会话和 multi-agent 子代理全链路可用。
+> `Codex CLI 0.144.1` 已实测主会话和 multi-agent 子代理全链路可用。
 > 内置 worker 可能先尝试 `gpt-5.6-luna` 或 `gpt-5.4`；网关没有对应渠道时
 > 会出现少量 404，随后由 Codex 回落到可用模型。自定义 agent 的模型覆盖是否
 > 直接生效取决于 Codex 版本；0.144.1 的实测主要依赖自动回落。
@@ -165,38 +188,35 @@ Codex 工具兼容现状：

 ## 已知限制

-### 超大流式请求
-
-上游流式断流有两个独立触发维度，状态不同：
+### `instructions` / `tools` 大体量流式断流

 > [!WARNING]
-> **instructions + tools 合计超过约 64.5 KB** 的流式请求，上游会在推理阶段
-> 静默断连（纯 EOF，无 error / 终态事件）；同请求非流式总是成功，`input`
-> 正文完全不计入。2026-07-13 定位（字节级二分），**2026-07-16 复测仍存在**
-> （70.4 KB 断 / 59.7 KB 过，Chicago，API Key 与签名行为一致）。
+> `instructions` 与 `tools` 两个字段的原始 JSON 值合计超过约 **64.5 KB** 时，
+> 上游流式请求可能在推理阶段静默断连：连接直接 EOF，不发送 `error` 或终态事件。
+> 同一请求改为非流式实测可正常完成；单独扩大 `input` 未触发该限制。

-> [!NOTE]
-> **完整请求体超过约 82 KB**（含 input）的纯体积断流（2026-07-15 定位）
-> **已被上游修复**：2026-07-16 复核 83 KB、真实 codex 形态 104.5 KB、200 KB、
-> 400 KB 流式均正常完成（Chicago 与 Phoenix 两区、签名与 API Key 两路径对照）。
+该问题于 2026-07-13 通过字节级二分定位，2026-07-16 在 Chicago 复测仍存在：
+`70.4 KB` 断流、`59.7 KB` 正常，API Key 与签名鉴权表现一致。本文及设置页中的
+`KB` 均按 `1024 B` 计算。

-网关当前行为：
+| 协议 | 网关保护 | 客户端表现 |
+| --- | --- | --- |
+| Responses | 保险丝默认开启；超过 `60 KB` 时改走非流式上游，并合成最小 SSE 序列 | 结果语义保留，但不再增量输出 |
+| Chat Completions / Messages | 客户端尚未收到内容就断流时，自动改用非流式重做 | 合成对应 chunk / event 序列 |
+| 已开始输出的流 | 无法透明重试；调用日志记录提前终止 | 客户端可能只收到部分事件 |

- **Chat Completions / Messages**：若上游在客户端收到任何内容前断流，自动用
-  非流式重做，并合成对应 chunk / event 序列（可兜住 64.5 KB 断流）
- **Responses**：直通协议中途无法透明重试（客户端已收到事件）。流式保险丝按
-  `instructions + tools` 字节和判定：超过阈值时预防性改非流式上游 + 合成最小
-  SSE 事件序列（`response.created` → `response.output_item.done` →
-  `response.completed`），语义保留但无增量输出。默认开、60 KB，可在
-  **设置 → AI → 流式保险丝** 调整或关闭
- **已开始输出的流**：不能透明重试；调用日志会记录提前终止，客户端可能只拿到
-  部分事件
+Responses 合成的最小事件序列为：`response.created` →
+`response.output_item.done` → `response.completed`。保险丝可在
+**设置 → AI → 流式保险丝** 调整或关闭。

-### grok 服务端搜索工具默认注入
+<details>
+<summary><strong>历史问题：完整请求体体积断流（已由上游修复）</strong></summary>

-对 `xai.` 前缀模型的 Responses 请求，网关按开关默认注入 `web_search` /
-`x_search` 工具；请求 tools 已包含同名工具时保持原样，不覆盖参数。默认双开，
-可在 **设置 → AI → grok 服务端搜索工具** 关闭。
+2026-07-15 曾在完整请求体约 `82 KB`（含 `input`）时观测到纯体积流式断流。
+2026-07-16 复核 `83 KB`、真实 Codex 形态 `104.5 KB`、`200 KB` 与 `400 KB`
+请求均正常完成；Chicago 与 Phoenix、签名与 API Key 两条路径结果一致。
+
+</details>

 ### ZDR 与文件输入

@@ -208,16 +228,20 @@ File content is currently unsupported for ZDR customers

 网关强制 `store:false`，属于 ZDR 请求形态，因此当前不能通过该端点上传或引用文件。

-### 规格与实测边界
-
-本项目提供的是兼容接口，而不是 OpenAI、Anthropic 或 xAI 协议的完整实现。
-部分 OCI OpenAI 兼容行为来自实测，未见 Oracle 文档合同，可能随上游调整。
-
 <a id="compatibility"></a>

 ## 字段兼容矩阵

-矩阵基线：
+> [!IMPORTANT]
+> 本项目提供兼容接口，而不是 OpenAI、Anthropic 或 xAI 协议的完整实现。部分 OCI
+> OpenAI 兼容行为来自实测，未见 Oracle 文档合同，可能随上游调整。
+
+### 矩阵索引
+
+[Responses](#compat-responses) · [Chat Completions](#compat-chat) · [Messages](#compat-messages) · [Embeddings](#compat-embeddings) · [语音生成](#compat-audio) · [Rerank](#compat-rerank) · [Moderations](#compat-moderations) · [Models](#compat-models)
+
+<details>
+<summary><strong>展开参考规格</strong></summary>

 - [OpenAI Responses](https://developers.openai.com/api/reference/resources/responses/methods/create)
 - [OpenAI Chat Completions](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)
@@ -227,6 +251,8 @@ File content is currently unsupported for ZDR customers
 - [Anthropic Messages](https://platform.claude.com/docs/en/api/messages/create)
 - [Cohere Rerank](https://docs.cohere.com/reference/rerank)

+</details>
+
 | 标记 | 含义 |
 | :---: | --- |
 | ✅ | 网关直接支持 |
@@ -234,6 +260,8 @@ File content is currently unsupported for ZDR customers
 | 🔄 | 网关执行字段或协议转换后支持 |
 | ◐ | 部分支持、存在前置条件或语义降级 |

+<a id="compat-responses"></a>
+
 ### OpenAI Responses

 **`POST /ai/v1/responses` · 无状态主接口**
@@ -255,12 +283,12 @@ Codex 工具兼容改写。请求会重新编码，不承诺字节级原样转
 | `reasoning` | ➡️ | 整个对象保留；`effort` 不校验档位 |
 | `tool_choice` | ◐ | 普通形态保留；namespace 对象会重限定，全部工具被剥离时删除 |
 | `store` | 🔄 | 无论客户端传什么，上游请求都强制改写为 `false` |
-| `stream` | ◐ | 支持 SSE；网关按 instructions+tools 字节和触发预防性非流式回退（保险丝，默认开 60 KB，见[已知限制](#limitations)） |
+| `stream` | ◐ | 支持 SSE；`instructions` 与 `tools` 的原始 JSON 值合计超过保险丝阈值时，预防性改走非流式上游（默认开启、`60 KB`，见[已知限制](#limitations)） |
 | 其余标准与未知顶层字段 | ➡️ | `context_management`、`include`、`metadata`、`prompt`、`prompt_cache_key`、`service_tier`、`truncation`、`user` 等均保留，由 OCI 决定是否接受 |

 </details>

-<details open>
+<details>
 <summary><strong>工具兼容</strong></summary>

 | 工具或参数 | 状态 | 网关行为 |
@@ -270,7 +298,7 @@ Codex 工具兼容改写。请求会重新编码，不承诺字节级原样转
 | `tools[].type=mcp` | ➡️ | 远程 MCP 由上游直连，`server_url`、`require_approval`、`authorization` 等保留 |
 | `tools[].type=namespace` | 🔄 | 子 `function` 上提并限定命名；响应、历史调用和 `tool_choice` 会反向还原；组内非 `function` 子工具被剥离 |
 | `tools[].type=custom` | ◐ | 顶层非 `apply_patch` 工具转为带 `input` schema 的 `function`；响应与多轮历史双向回转；`format` 会删除 |
-| `custom:apply_patch` | ◐ | 整体剥离；grok 系未针对 Codex 补丁格式训练，模型应回落其他编辑方式 |
+| `custom:apply_patch` | ◐ | 整体剥离；Grok 系未针对 Codex 补丁格式训练，模型应回落其他编辑方式 |
 | `tools[].type=tool_search` | ◐ | 请求可被接受，但工具本身直接剥离 |
 | `web_search.external_web_access=true` | 🔄 | 删除上游不识别的字段，保留 `web_search` |
 | `web_search.external_web_access=false` | ◐ | 上游没有“仅缓存检索”对应能力，按不越权原则剥离整个工具 |
@@ -293,6 +321,8 @@ Codex 工具兼容改写。请求会重新编码，不承诺字节级原样转
 - 未知模型返回 404，无可用渠道返回 503
 - 上游错误使用 OpenAI 风格错误外壳，但不保证字段与标准 OpenAI 完全一致

+<a id="compat-chat"></a>
+
 ### OpenAI Chat Completions

 **`POST /ai/v1/chat/completions` · 存量客户端兼容层**
@@ -348,6 +378,8 @@ Codex 工具兼容改写。请求会重新编码，不承诺字节级原样转
  `prompt_tokens_details.cached_tokens`
 - 已开始输出的流中断不会转换成标准 SSE 错误事件

+<a id="compat-messages"></a>
+
 ### Anthropic Messages

 **`POST /ai/v1/messages` · Anthropic 协议转换层**
@@ -401,6 +433,8 @@ Codex 工具兼容改写。请求会重新编码，不承诺字节级原样转
 - usage 只保留 `input_tokens`、`output_tokens` 与 `cache_read_input_tokens`
 - 流式上游错误与无终态断流会转成 Anthropic `error` 事件

+<a id="compat-embeddings"></a>
+
 ### OpenAI Embeddings

 **`POST /ai/v1/embeddings` · 向量化专用端点**
@@ -418,6 +452,8 @@ Codex 工具兼容改写。请求会重新编码，不承诺字节级原样转

 响应使用标准 `object:"list"` 外壳，向量为 `float32` 数组，不支持流式。

+<a id="compat-audio"></a>
+
 ### 语音生成

 两个端点最终使用同一 OCI xAI TTS 上游与渠道调度：
@@ -458,6 +494,8 @@ Codex 工具兼容改写。请求会重新编码，不承诺字节级原样转
 - 不提供 HTTP 流式音频或 WebSocket 代理
 - 无 token 用量口径，调用日志只记时延与渠道

+<a id="compat-rerank"></a>
+
 ### Rerank

 **`POST /ai/v1/rerank` · Cohere / Jina 风格协议**
@@ -475,6 +513,8 @@ Codex 工具兼容改写。请求会重新编码，不承诺字节级原样转
 `max_tokens_per_doc` 与未知字段静默忽略。响应按相关度降序，
 `results[].index` 指向输入下标，`relevance_score` 为 0～1 浮点；无 token 用量口径。

+<a id="compat-moderations"></a>
+
 ### Moderations

 **`POST /ai/v1/moderations` · OpenAI 外壳映射 OCI Guardrails**
@@ -496,6 +536,8 @@ Codex 工具兼容改写。请求会重新编码，不承诺字节级原样转
 - 实测中文人名与手机号识别较弱，英文 PII 识别正常
 - 响应 `model` 恒为 `oci-guardrails`

+<a id="compat-models"></a>
+
 ### Models

 **`GET /ai/v1/models` · 当前密钥可见模型列表**
@@ -512,7 +554,7 @@ Codex 工具兼容改写。请求会重新编码，不承诺字节级原样转

 <a id="implementation"></a>

-## 实现索引
+## 附录：实现索引

 | 端点 / 能力 | 主要实现 |
 | --- | --- |
@@ -526,3 +568,5 @@ Codex 工具兼容改写。请求会重新编码，不承诺字节级原样转

 本文是兼容性快照，不替代 Swagger。标准接口、Codex 客户端与 OCI 上游均可能
 变化，最终行为以当前版本代码、运行时 Swagger 和实测结果为准。
+
+[返回顶部](#top)