From 7002e42c0621eeab2362516844455191c8b5b785 Mon Sep 17 00:00:00 2001 From: Wang Defa <1+wangdefa@noreply.gitea.bcde.io> Date: Thu, 16 Jul 2026 12:47:57 +0800 Subject: [PATCH] =?UTF-8?q?=E7=BE=8E=E5=8C=96=E9=A1=B9=E7=9B=AE=E4=B8=8EAI?= =?UTF-8?q?=E7=BD=91=E5=85=B3=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 124 +++++++++++++++++++++------------ docs/AI网关.md | 182 ++++++++++++++++++++++++++++++------------------- 2 files changed, 194 insertions(+), 112 deletions(-) diff --git a/README.md b/README.md index a23d881..8a80aad 100644 --- a/README.md +++ b/README.md @@ -6,12 +6,14 @@ **自托管的 OCI 多租户管理面板与 GenAI 兼容网关** -![Release](https://img.shields.io/github/v/release/wangdefaa/oci-portal?display_name=tag) -![Go](https://img.shields.io/badge/Go-1.26.5-00ADD8?logo=go&logoColor=white) -![Docker](https://img.shields.io/badge/Docker-amd64%20%7C%20arm64-2496ED?logo=docker&logoColor=white) -![License](https://img.shields.io/badge/License-MIT-blue) +[![Release](https://img.shields.io/github/v/release/wangdefaa/oci-portal?display_name=tag)](https://github.com/wangdefaa/oci-portal/releases/latest) +[![Go](https://img.shields.io/badge/Go-1.26.5-00ADD8?logo=go&logoColor=white)](go.mod) +[![Docker](https://img.shields.io/badge/Docker-amd64%20%7C%20arm64-2496ED?logo=docker&logoColor=white)](docker-compose.yml) +[![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE) -[快速开始](#快速开始) · [核心能力](#核心能力) · [生产部署](#生产部署) · [AI 网关](#ai-网关) · [开发](#开发) +[界面预览](#界面预览) · [核心能力](#核心能力) · [快速开始](#快速开始) · [生产部署](#生产部署) · [AI 网关](#ai-网关) · [开发](#开发) + +[AI 网关文档](docs/AI网关.md) · [OpenAPI](docs/swagger.yaml) · [更新日志](CHANGELOG.md) · [前端仓库](https://github.com/wangdefaa/oci-portal-dash) @@ -21,27 +23,36 @@ OCI Portal 将多份 OCI API Key、云资源、自动化任务、审计事件和 ## 界面预览 -| 总览 | 登录 | -| --- | --- | -| ![总览](docs/assets/screenshot-overview.png) | ![登录](docs/assets/screenshot-signin.png) | +

+ OCI Portal 总览 +

-| 租户 | 任务 | -| --- | --- | -| ![租户](docs/assets/screenshot-tenants.png) | ![任务](docs/assets/screenshot-tasks.png) | +
+展开更多界面截图 -| AI 网关 | 通知设置 | +| 登录 | 租户 | | --- | --- | -| ![AI 网关](docs/assets/screenshot-ai-gateway.png) | ![通知设置](docs/assets/screenshot-settings-notify.png) | +| ![登录](docs/assets/screenshot-signin.png) | ![租户](docs/assets/screenshot-tenants.png) | + +| 任务 | AI 网关 | +| --- | --- | +| ![任务](docs/assets/screenshot-tasks.png) | ![AI 网关](docs/assets/screenshot-ai-gateway.png) | + +| 通知设置 | +| --- | +| ![通知设置](docs/assets/screenshot-settings-notify.png) | + +
## 核心能力 -- **租户与区域**：集中管理多份 OCI API Key，支持分组、批量测活、账户画像、订阅区域缓存与区域切换；私钥和口令使用 AES-256-GCM 加密落库 -- **计算、网络与存储**：实例创建与电源操作、公网 IP、IPv6、VNIC、串行控制台连接，VCN / 子网 / 安全列表，引导卷与块存储挂载，限额和成本查询 -- **自动化任务**：抢机、租户测活、成本同步、AI 渠道探测四类 cron 任务，提供执行日志、重叠执行防护、熔断与结果通知 -- **网页控制台**：浏览器内使用 xterm 串行终端和 noVNC，通过 OCI 控制台连接建立两跳 SSH 隧道 -- **身份与审计**：IAM 用户、MFA、API Key、密码策略、SAML 身份提供商、通知收件人和多 Identity Domain 管理；OCI Audit 事件可经 Service Connector Hub 与 Notifications 回传，关键事件按类别通过「云端事件」通知推送 -- **通知与安全**：Telegram、Webhook、ntfy、Bark、SMTP 五类渠道；JWT、bcrypt、TOTP、OIDC / GitHub 登录、登录锁定、IP 限速、会话撤销和系统操作审计 -- **AI 网关**：提供 OpenAI Responses、Chat Completions、Embeddings 与 Anthropic Messages 兼容接口，支持渠道分组、加权路由、熔断探测、模型黑白名单、密钥管理和调用日志 +| 能力域 | 覆盖范围 | +| --- | --- | +| **租户与云资源** | 多 OCI API Key、分组、批量测活、账户画像、订阅区域缓存与切换；实例创建与电源操作、VNIC、公网 IP、IPv6、VCN、安全列表、引导卷、块存储挂载、限额与成本查询 | +| **自动化与控制台** | 抢机、租户测活、成本同步、AI 渠道探测；执行日志、重叠防护、熔断与结果通知；xterm 串行终端、noVNC 和 OCI 控制台连接两跳 SSH 隧道 | +| **身份与审计** | IAM 用户、MFA、API Key、密码策略、SAML、通知收件人与多 Identity Domain；通过 Service Connector Hub 与 Notifications 接收并分类推送 OCI Audit 事件 | +| **通知与安全** | Telegram、Webhook、ntfy、Bark、SMTP；AES-256-GCM、JWT、bcrypt、TOTP、OIDC / GitHub 登录、登录锁定、IP 限速、会话撤销和操作审计 | +| **AI 网关** | OpenAI Responses、Chat Completions、Embeddings 与 Anthropic Messages；渠道分组、加权路由、熔断探测、模型治理、密钥管理和调用日志 | ## 运行形态 @@ -57,7 +68,9 @@ OCI Portal 将多份 OCI API Key、云资源、自动化任务、审计事件和 └─────────────────────────────────────────────────────────────────┘ ``` -默认推荐 SQLite 单实例部署。MySQL 和 PostgreSQL 适配仍属 experimental，不应据此推断服务支持多副本并发运行。 +> [!NOTE] +> 默认推荐 SQLite 单实例部署。MySQL 和 PostgreSQL 适配仍属 experimental， +> 不应据此推断服务支持多副本并发运行。 ## 快速开始 @@ -65,6 +78,10 @@ OCI Portal 将多份 OCI API Key、云资源、自动化任务、审计事件和 前置条件：Docker、Docker Compose v2、OpenSSL。 +> [!CAUTION] +> `.env` 中的 `DATA_KEY` 用于解密 OCI 私钥、口令和渠道凭据。首次生成后必须长期 +> 保存；升级或重装时不要覆盖，否则已有密文将无法恢复。 + 1. 克隆仓库并生成一份需要长期保存的 `.env`： ```bash @@ -79,19 +96,27 @@ OCI Portal 将多份 OCI API Key、云资源、自动化任务、审计事件和 chmod 600 .env ``` -2. 准备数据目录并启动： +2. 准备数据目录： ```bash mkdir -p data + ``` - # Linux bind mount 需要让镜像内的 nonroot 用户（uid 65532）可写。 + Linux 使用 bind mount 时，需要让镜像内的 nonroot 用户（uid `65532`）可写； + Docker Desktop 用户通常不需要执行： + + ```bash sudo chown 65532:65532 data + ``` +3. 启动并检查状态： + + ```bash docker compose up -d docker compose ps ``` -3. 查看初始管理员密码并登录： +4. 查看初始管理员密码并登录： ```bash grep '^ADMIN_PASSWORD=' .env @@ -99,7 +124,14 @@ OCI Portal 将多份 OCI API Key、云资源、自动化任务、审计事件和 访问 `http://127.0.0.1:18888`，默认用户名为 `admin`。 -> `DATA_KEY` 用于解密数据库中的 OCI 私钥、口令和渠道凭据。它只能生成一次并持续复用；丢失或更换后，已有密文无法恢复。请将 `.env` 与 `data/oci-portal.db` 一起备份。 + 启动异常时查看最近日志： + + ```bash + docker compose logs --tail=100 oci-portal + ``` + +> [!TIP] +> 请将 `.env` 与 `data/oci-portal.db` 成对备份；恢复时两者必须匹配。 ### 二进制运行 @@ -107,6 +139,8 @@ Release 提供 Linux amd64 / arm64 二进制。以下以 amd64 为例；arm64 ```bash curl -fLO https://github.com/wangdefaa/oci-portal/releases/latest/download/oci-portal-server-linux-amd64 +curl -fLO https://github.com/wangdefaa/oci-portal/releases/latest/download/SHA256SUMS +grep 'oci-portal-server-linux-amd64$' SHA256SUMS | sha256sum -c - chmod +x oci-portal-server-linux-amd64 # 复用上文生成并妥善保存的 .env。 @@ -142,7 +176,9 @@ CGO_ENABLED=0 go build -trimpath -o bin/oci-portal-server ./cmd/server ## 生产部署 -服务本身只提供 HTTP。除本机试用外，应保持服务仅监听回环地址或容器内部网络，并由 TLS 反向代理提供 HTTPS；否则管理员密码、JWT、AI 密钥和租户凭据会经明文连接传输。 +> [!WARNING] +> 服务本身只提供 HTTP。除本机试用外，应仅监听回环地址或容器内部网络，并由 +> TLS 反向代理提供 HTTPS；否则管理员密码、JWT、AI 密钥和租户凭据会经明文传输。 ### Caddy @@ -229,29 +265,31 @@ OpenAPI 文件随仓库维护：[`docs/swagger.yaml`](docs/swagger.yaml) · [`do ### 环境变量 -| 变量 | 必填 | 默认值 | 说明 | +| 变量 | 使用条件 | 默认值 | 说明 | | --- | :---: | --- | --- | -| `DATA_KEY` | 是 | — | 敏感字段加密主密钥；必须持久保存，不能随意轮换 | -| `JWT_SECRET` | 是 | — | JWT 签名密钥；更换会使已有登录令牌失效 | -| `ADMIN_USERNAME` | 否 | `admin` | 初始管理员用户名 | +| `DATA_KEY` | 必填 | — | 敏感字段加密主密钥；必须持久保存，不能随意轮换 | +| `JWT_SECRET` | 必填 | — | JWT 签名密钥；更换会使已有登录令牌失效 | +| `ADMIN_USERNAME` | 可选 | `admin` | 初始管理员用户名 | | `ADMIN_PASSWORD` | 首次启动 | — | 仅在数据库无用户时创建管理员，不会重置已有密码 | -| `ADDR` | 否 | `:8080` | HTTP 监听地址 | -| `DB_DRIVER` | 否 | `sqlite` | `sqlite` / `mysql` / `postgres`；后两者为 experimental | +| `ADDR` | 可选 | `:8080` | HTTP 监听地址 | +| `DB_DRIVER` | 可选 | `sqlite` | `sqlite` / `mysql` / `postgres`；后两者为 experimental | | `DB_PATH` | SQLite | `oci-portal.db` | SQLite 文件路径 | -| `DB_DSN` | 外部数据库 | — | MySQL 需 `parseTime=True`；不要在日志或文档中暴露凭据 | -| `PUBLIC_URL` | 否 | — | 面板公网基址，作为 OAuth 回调和日志回传引导的回退值 | -| `TZ` | 否 | 系统时区 | cron 表达式的解释时区；容器示例使用 `Asia/Shanghai` | -| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | 否 | — | Go 标准出站代理变量；面板内显式代理配置优先用于对应业务 | -| `SWAGGER` | 否 | 关闭 | 设为 `1` 时开放 Swagger UI | -| `GIN_MODE` | 否 | `release` | `debug` / `release` | +| `DB_DSN` | MySQL / PostgreSQL | — | MySQL 需 `parseTime=True`；不要在日志或文档中暴露凭据 | +| `PUBLIC_URL` | 可选 | — | 面板公网基址，作为 OAuth 回调和日志回传引导的回退值 | +| `TZ` | 可选 | 系统时区 | cron 表达式的解释时区；容器示例使用 `Asia/Shanghai` | +| `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` | 可选 | — | Go 标准出站代理变量；面板内显式代理配置优先用于对应业务 | +| `SWAGGER` | 可选 | 关闭 | 设为 `1` 时开放 Swagger UI | +| `GIN_MODE` | 可选 | `release` | `debug` / `release` | ## 升级与备份 -- 升级前同时备份 `.env` 和数据库；SQLite Compose 部署的数据文件为 `data/oci-portal.db` -- 保持 `DATA_KEY` 不变；只恢复数据库而没有原密钥，敏感字段无法解密 -- 服务启动时会自动执行数据库迁移；跨版本升级前先阅读 [CHANGELOG](CHANGELOG.md) -- Compose 部署使用 `docker compose pull && docker compose up -d` 更新镜像 -- OCI API Key 应遵循最小权限原则；生产环境保持 Swagger 关闭并限制管理面访问来源 +1. 阅读 [CHANGELOG](CHANGELOG.md)，确认目标版本的行为变化。 +2. 备份 `.env` 和数据库。SQLite Compose 部署建议先停止服务，再复制 + `data/oci-portal.db`，避免在线复制产生不一致快照。 +3. 保持原 `DATA_KEY` 不变；只有数据库而没有对应密钥时，敏感字段无法解密。 +4. Compose 部署执行 `docker compose pull`，再执行 `docker compose up -d`；服务启动时 + 会自动完成数据库迁移。 +5. 生产环境保持 Swagger 关闭、限制管理面访问来源，并为 OCI API Key 配置最小权限。 ## 开发 diff --git a/docs/AI网关.md b/docs/AI网关.md index 018b16a..d12cac4 100644 --- a/docs/AI网关.md +++ b/docs/AI网关.md @@ -1,23 +1,33 @@ + + +
+ +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) + +
+ > [!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 | +| 会话模式 | 无状态，客户端携带完整上下文 | @@ -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":"你好，请用一句话介绍自己。"}' +``` + ## 端点一览 @@ -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** | +| 向量、语音、重排与安全审核 | 对应专用端点 | @@ -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 → 模型治理** | + ## 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 服务端搜索工具默认注入 +
+历史问题：完整请求体体积断流（已由上游修复） -对 `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 两条路径结果一致。 + +
### ZDR 与文件输入 @@ -208,16 +228,20 @@ File content is currently unsupported for ZDR customers 网关强制 `store:false`，属于 ZDR 请求形态，因此当前不能通过该端点上传或引用文件。 -### 规格与实测边界 - -本项目提供的是兼容接口，而不是 OpenAI、Anthropic 或 xAI 协议的完整实现。 -部分 OCI OpenAI 兼容行为来自实测，未见 Oracle 文档合同，可能随上游调整。 - ## 字段兼容矩阵 -矩阵基线： +> [!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) + +
+展开参考规格 - [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) +
+ | 标记 | 含义 | | :---: | --- | | ✅ | 网关直接支持 | @@ -234,6 +260,8 @@ File content is currently unsupported for ZDR customers | 🔄 | 网关执行字段或协议转换后支持 | | ◐ | 部分支持、存在前置条件或语义降级 | + + ### 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 决定是否接受 | -
+
工具兼容 | 工具或参数 | 状态 | 网关行为 | @@ -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 完全一致 + + ### OpenAI Chat Completions **`POST /ai/v1/chat/completions` · 存量客户端兼容层** @@ -348,6 +378,8 @@ Codex 工具兼容改写。请求会重新编码，不承诺字节级原样转 `prompt_tokens_details.cached_tokens` - 已开始输出的流中断不会转换成标准 SSE 错误事件 + + ### Anthropic Messages **`POST /ai/v1/messages` · Anthropic 协议转换层** @@ -401,6 +433,8 @@ Codex 工具兼容改写。请求会重新编码，不承诺字节级原样转 - usage 只保留 `input_tokens`、`output_tokens` 与 `cache_read_input_tokens` - 流式上游错误与无终态断流会转成 Anthropic `error` 事件 + + ### OpenAI Embeddings **`POST /ai/v1/embeddings` · 向量化专用端点** @@ -418,6 +452,8 @@ Codex 工具兼容改写。请求会重新编码，不承诺字节级原样转 响应使用标准 `object:"list"` 外壳，向量为 `float32` 数组，不支持流式。 + + ### 语音生成 两个端点最终使用同一 OCI xAI TTS 上游与渠道调度： @@ -458,6 +494,8 @@ Codex 工具兼容改写。请求会重新编码，不承诺字节级原样转 - 不提供 HTTP 流式音频或 WebSocket 代理 - 无 token 用量口径，调用日志只记时延与渠道 + + ### Rerank **`POST /ai/v1/rerank` · Cohere / Jina 风格协议** @@ -475,6 +513,8 @@ Codex 工具兼容改写。请求会重新编码，不承诺字节级原样转 `max_tokens_per_doc` 与未知字段静默忽略。响应按相关度降序， `results[].index` 指向输入下标，`relevance_score` 为 0～1 浮点；无 token 用量口径。 + + ### Moderations **`POST /ai/v1/moderations` · OpenAI 外壳映射 OCI Guardrails** @@ -496,6 +536,8 @@ Codex 工具兼容改写。请求会重新编码，不承诺字节级原样转 - 实测中文人名与手机号识别较弱，英文 PII 识别正常 - 响应 `model` 恒为 `oci-guardrails` + + ### Models **`GET /ai/v1/models` · 当前密钥可见模型列表** @@ -512,7 +554,7 @@ Codex 工具兼容改写。请求会重新编码，不承诺字节级原样转 -## 实现索引 +## 附录：实现索引 | 端点 / 能力 | 主要实现 | | --- | --- | @@ -526,3 +568,5 @@ Codex 工具兼容改写。请求会重新编码，不承诺字节级原样转 本文是兼容性快照，不替代 Swagger。标准接口、Codex 客户端与 OCI 上游均可能 变化，最终行为以当前版本代码、运行时 Swagger 和实测结果为准。 + +[返回顶部](#top)