AI 网关切换 OpenAI 兼容面并移除 chat 端点,新增模型黑白名单

README.md

@@ -34,7 +34,7 @@
 - **资源管理**：实例（含创建/电源操作/更换公网 IP/IPv6/VNIC/引导卷）、VCN/子网/安全列表、块存储、限额与成本查询，多区域/多区间支持
 - **抢机任务**：cron 周期尝试创建实例直到成功，支持熔断与通知
 - **网页控制台**：实例串行控制台（xterm）与 VNC（noVNC），两跳 SSH 隧道
-- **AI 网关**：OpenAI / Anthropic 兼容端点转发 OCI GenAI（对话/Responses/Embeddings），号池渠道加权负载均衡、熔断探测、密钥管理与用量日志
+- **AI 网关**：OpenAI Responses / Anthropic Messages / Embeddings 兼容端点转发 OCI GenAI，号池渠道加权负载均衡、熔断探测、密钥管理与用量日志；对话统一走 OCI OpenAI 兼容面（xai / meta / openai 厂商模型，流式事件与推理增量原样保真），支持 xAI Grok 服务端工具 `web_search` / `x_search`（格式同 xAI 官方 Agent Tools，仅非流式）——兼容面属实测可用但未见 Oracle 文档承诺的能力，行为可能随上游调整
 - **日志回传**：OCI Audit 事件经 Connector Hub → Notifications HTTPS 订阅回传入库，一键创建链路；自定义告警规则（事件类型/来源 IP 白名单/资源/频率阈值）命中即推送
 - **租户治理**：IAM 用户/MFA/API Key 管理、密码策略、身份提供商（SAML）、通知收件人；多 Identity Domain 租户可按域切换管理
 - **安全**：JWT + bcrypt（凭据变更旧令牌立即失效，可一键撤销全部会话）、TOTP 两步验证、OIDC/GitHub 外部登录、登录锁定、IP 限速、真实 IP 头可配、请求体/超时防护、系统操作审计
@@ -60,7 +60,7 @@ mkdir -p ./data && sudo chown 65532:65532 ./data
 DATA_KEY=$(openssl rand -hex 32) JWT_SECRET=$(openssl rand -hex 32) ADMIN_PASSWORD=<初始密码> docker compose up -d
 ```
 
-默认只监听 `127.0.0.1:18888`;公网访问须置于 TLS 反向代理之后,见下文「反向代理」。
+默认只监听 `127.0.0.1:18888`；公网访问须置于 TLS 反向代理之后，见下文「反向代理」。
 
 ### 源码构建（单文件，含前端）
 
@@ -148,6 +148,87 @@ services:
 - 反代默认追加的 `X-Forwarded-For` 用于还原真实客户端 IP，系统日志留痕、登录锁定与 IP 限速都依赖它
 - 请求体上限建议与后端一致：`/api/*` 1MB、`/ai/*` 10MB（Caddy 用 `request_body` 按前缀分层）
 
+## AI 网关接口
+
+对外提供 OpenAI / Anthropic 兼容端点，转发 OCI GenAI On-Demand 推理。鉴权用面板创建的 AI 密钥，`Authorization: Bearer sk-...` 与 `x-api-key: sk-...` 双头均可；密钥可绑定渠道分组实现路由隔离，也可配置模型白名单（白名单外调用 404，模型列表只返回交集）。请求体上限 10MB。
+
+| 端点 | 协议 | 流式 |
+| --- | --- | --- |
+| `POST /ai/v1/responses` | OpenAI Responses（无状态子集） | SSE 支持（服务端工具除外） |
+| `POST /ai/v1/messages` | Anthropic Messages | SSE 支持 |
+| `POST /ai/v1/embeddings` | OpenAI Embeddings | — |
+| `GET /ai/v1/models` | OpenAI 模型列表（来自渠道模型目录） | — |
+
+对话端点统一转发 OCI OpenAI 兼容面（`/actions/v1/responses`），因此仅提供该面支持的 `xai.` / `meta.` / `openai.` 前缀模型；google / cohere 对话模型不在兼容面供给（上游 400），不再提供（cohere embed 模型不受影响）。兼容面属实测可用但无 Oracle 文档承诺的能力，行为可能随上游调整。**Chat Completions（`/ai/v1/chat/completions`）端点已移除**，请迁移到 Responses 或 Messages。
+
+以下各表对照网关行为：✅ 转发上游；⚠️ 接受但忽略（静默丢弃，不影响请求）；❌ 拒绝（400，不发上游）。
+
+### Responses 字段
+
+请求体除下列例外**原样直通上游**（未列字段一并转发，效果由上游决定）：
+
+| 字段 | 支持 | 说明 |
+| --- | --- | --- |
+| `model`、`input` | ✅ | `input` 接受 string 或 item 数组 |
+| `stream` | ✅ | SSE，上游原生事件流（含 gpt-oss 推理增量）；与服务端工具互斥 |
+| `reasoning.effort` | ✅ | 直达上游不限档位，见下「推理力度」 |
+| `store` | ⚠️ | 网关无状态，强制改写为 `false` |
+| `previous_response_id`、`conversation`、`background` | ❌ | 网关不保存历史，请求需自带完整上下文 |
+| `web_search` / `x_search` / `function` 之外的工具类型 | ❌ | 如 `file_search`、`code_interpreter`、`mcp` |
+
+**服务端工具**：`tools` 支持 `{"type":"web_search"}` 与 `{"type":"x_search"}`（xAI Grok 官方 Agent Tools 格式，可与 `function` 混用），响应保留 `web_search_call` 输出项与引用；**仅非流式**。响应 `usage.input_tokens_details.cached_tokens` 透传缓存命中量。
+
+### Anthropic Messages 字段
+
+网关把 Messages 请求转换为 Responses 请求送上游，响应（含流式事件序列）转回 Anthropic 形态：
+
+| 字段 | 支持 | 说明 |
+| --- | --- | --- |
+| `model`、`max_tokens`、`messages` | ✅ | `max_tokens` 必填；content 块支持 `text` / `image` / `tool_use` / `tool_result`，其余块类型 400 |
+| `system` | ✅ | string 或块数组，映射为 `instructions` |
+| `temperature`、`top_p` | ✅ | |
+| `stream` | ✅ | SSE，标准 Anthropic 事件序列（`message_start` → `content_block_*` → `message_delta` → `message_stop`） |
+| `tools`、`tool_choice` | ✅ | 映射为 Responses `function` 工具；`tool_choice` 支持 `auto` / `any` / `none` / `tool` |
+| `output_config.effort` | ✅ | 直达上游不限档位，见下「推理力度」 |
+| `stop_sequences`、`top_k`、`metadata`、`thinking`、`service_tier` | ⚠️ | Responses 面无对应物，静默忽略 |
+
+模型的思考输出（reasoning）不转为 `thinking` 块，静默丢弃；`usage.cache_read_input_tokens` 透传缓存命中量。
+
+### Embeddings 字段
+
+| 字段 | 支持 | 说明 |
+| --- | --- | --- |
+| `model`、`input` | ✅ | `input` 接受 string 或数组 |
+| `dimensions` | ✅ | |
+| `encoding_format`、`user` | ⚠️ | 输出恒为 float 数组 |
+
+### 推理力度（effort）
+
+两个对话协议各以原生字段控制推理深度，取值直达上游不做档位校验：
+
+| 协议 | 字段 |
+| --- | --- |
+| Responses | `reasoning.effort` |
+| Anthropic Messages | `output_config.effort`（转小写后透传） |
+
+是否支持、可用档位与实际效果由模型决定（2026-07 兼容面实测）：
+
+| 模型 | 支持档位 | 实测行为 |
+| --- | --- | --- |
+| `xai.grok-4.3` | `none` / `minimal` / `low` / `medium` / `high` | 全部生效：`none` 完全关闭推理，默认 `low`，`high` 推理量最大 |
+| `openai.gpt-oss-*` | `minimal` / `low` / `medium` / `high` | `none` 被上游 400（Harmony 格式不支持）；思考计入 completion tokens |
+| `xai.grok-3-mini(-fast)` | 名义 `low` / `high` | 各档均被接受，但 `none` 并不关闭推理（仍产生思考） |
+| `meta.llama-*` | 接受任意档 | 非推理模型，参数无实际效果 |
+| `xai.grok-4.20-multi-agent*` | `low` / `medium` / `high` / `xhigh` | effort 控制并行 agent 数（4 / 16）而非推理深度 |
+| 其余 grok（`grok-3`、`grok-4`、`grok-4-fast-*`、`grok-4-1-fast-*`、`grok-code-fast-1`、`grok-4.20-*` 单/双型号全系） | 不支持 | 携带即被上游 400（`does not support parameter reasoningEffort`） |
+
+不携带该字段时网关不下发，行为由模型默认档位决定。
+
+### 通用行为
+
+- 未知模型 404；无可用渠道 503；单次请求最多尝试 3 个渠道（429/5xx/网络错误自动换渠道并计入熔断，模型级 400/404 换渠道不计熔断，其余 4xx 原样透传）；流式建立后绑定渠道，中断不重试
+- 调用计量（渠道、token 用量、缓存命中、时延、重试数）写入面板「调用日志」；密钥可按需开启限时内容抓取
+
 ## 环境变量
 
 | 变量 | 必填 | 默认值 | 说明 |