设置页AI Tab:网关设置入库、保险丝改维度与grok工具注入

2026-07-16 12:31:36 +08:00
parent 99b551401e
commit da7b29d2e3
11 changed files with 600 additions and 38 deletions
@@ -167,21 +167,37 @@ Codex 工具兼容现状：

 ### 超大流式请求

+上游流式断流有两个独立触发维度，状态不同：
+
 > [!WARNING]
-> 2026-07 实测：OCI xAI 兼容面对**完整请求体超过约 82 KB** 的流式请求，
-> 可能在推理阶段提前断流；该现象由请求体积触发，与工具构成或字符集无关，
-> 同一请求改为非流式可正常完成。
+> **instructions + tools 合计超过约 64.5 KB** 的流式请求，上游会在推理阶段
+> 静默断连（纯 EOF，无 error / 终态事件）；同请求非流式总是成功，`input`
+> 正文完全不计入。2026-07-13 定位（字节级二分），**2026-07-16 复测仍存在**
+> （70.4 KB 断 / 59.7 KB 过，Chicago，API Key 与签名行为一致）。

-网关按协议采取不同保护：
+> [!NOTE]
+> **完整请求体超过约 82 KB**（含 input）的纯体积断流（2026-07-15 定位）
+> **已被上游修复**：2026-07-16 复核 83 KB、真实 codex 形态 104.5 KB、200 KB、
+> 400 KB 流式均正常完成（Chicago 与 Phoenix 两区、签名与 API Key 两路径对照）。
+
+网关当前行为：

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

+### grok 服务端搜索工具默认注入
+
+对 `xai.` 前缀模型的 Responses 请求，网关按开关默认注入 `web_search` /
+`x_search` 工具；请求 tools 已包含同名工具时保持原样，不覆盖参数。默认双开，
+可在 **设置 → AI → grok 服务端搜索工具** 关闭。
+
 ### ZDR 与文件输入

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

 </details>
@@ -786,6 +786,27 @@ const docTemplate = `{
                }
            }
        },
+        "/api/v1/ai-model-catalog": {
+            "get": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "tags": [
+                    "AI 管理"
+                ],
+                "summary": "聚合模型目录",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/internal_api.itemsResponse-oci-portal_internal_service_AggregatedModel"
+                        }
+                    }
+                }
+            }
+        },
        "/api/v1/ai-models": {
            "get": {
                "security": [
@@ -839,7 +860,7 @@ const docTemplate = `{
                "summary": "更新 AI 网关全局设置",
                "parameters": [
                    {
-                        "description": "开启后已宣布弃用(即使未退役)的模型从列表与路由中排除",
+                        "description": "全量提交;保险丝阈值限 1..1024 KB",
                        "name": "body",
                        "in": "body",
                        "required": true,
@@ -854,6 +875,15 @@ const docTemplate = `{
                        "schema": {
                            "$ref": "#/definitions/internal_api.aiSettingsResponse"
                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
                    }
                }
            }
@@ -6050,7 +6080,22 @@ const docTemplate = `{
            "type": "object",
            "properties": {
                "filterDeprecated": {
+                    "description": "FilterDeprecated 开启后已宣布弃用(即使未退役)的模型从列表与路由中排除",
                    "type": "boolean"
+                },
+                "grokWebSearch": {
+                    "description": "GrokWebSearch / GrokXSearch 是 xai. 模型服务端搜索工具默认注入开关;\n请求 tools 已包含同名工具时不覆盖",
+                    "type": "boolean"
+                },
+                "grokXSearch": {
+                    "type": "boolean"
+                },
+                "streamGuardEnabled": {
+                    "description": "StreamGuardEnabled / StreamGuardKB 是 Responses 流式保险丝:\ninstructions+tools 合计超阈值(KB)的流式请求改非流式上游并合成 SSE",
+                    "type": "boolean"
+                },
+                "streamGuardKB": {
+                    "type": "integer"
                }
            }
        },
@@ -6621,6 +6666,17 @@ const docTemplate = `{
                }
            }
        },
+        "internal_api.itemsResponse-oci-portal_internal_service_AggregatedModel": {
+            "type": "object",
+            "properties": {
+                "items": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/oci-portal_internal_service.AggregatedModel"
+                    }
+                }
+            }
+        },
        "internal_api.itemsResponse-oci-portal_internal_service_NotifyChannelView": {
            "type": "object",
            "properties": {
@@ -9358,6 +9414,17 @@ const docTemplate = `{
                }
            }
        },
+        "oci-portal_internal_service.AggregatedModel": {
+            "type": "object",
+            "properties": {
+                "capability": {
+                    "type": "string"
+                },
+                "name": {
+                    "type": "string"
+                }
+            }
+        },
        "oci-portal_internal_service.AuditEventsView": {
            "type": "object",
            "properties": {
@@ -779,6 +779,27 @@
                }
            }
        },
+        "/api/v1/ai-model-catalog": {
+            "get": {
+                "security": [
+                    {
+                        "BearerAuth": []
+                    }
+                ],
+                "tags": [
+                    "AI 管理"
+                ],
+                "summary": "聚合模型目录",
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/internal_api.itemsResponse-oci-portal_internal_service_AggregatedModel"
+                        }
+                    }
+                }
+            }
+        },
        "/api/v1/ai-models": {
            "get": {
                "security": [
@@ -832,7 +853,7 @@
                "summary": "更新 AI 网关全局设置",
                "parameters": [
                    {
-                        "description": "开启后已宣布弃用(即使未退役)的模型从列表与路由中排除",
+                        "description": "全量提交;保险丝阈值限 1..1024 KB",
                        "name": "body",
                        "in": "body",
                        "required": true,
@@ -847,6 +868,15 @@
                        "schema": {
                            "$ref": "#/definitions/internal_api.aiSettingsResponse"
                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": {
+                                "type": "string"
+                            }
+                        }
                    }
                }
            }
@@ -6043,7 +6073,22 @@
            "type": "object",
            "properties": {
                "filterDeprecated": {
+                    "description": "FilterDeprecated 开启后已宣布弃用(即使未退役)的模型从列表与路由中排除",
                    "type": "boolean"
+                },
+                "grokWebSearch": {
+                    "description": "GrokWebSearch / GrokXSearch 是 xai. 模型服务端搜索工具默认注入开关;\n请求 tools 已包含同名工具时不覆盖",
+                    "type": "boolean"
+                },
+                "grokXSearch": {
+                    "type": "boolean"
+                },
+                "streamGuardEnabled": {
+                    "description": "StreamGuardEnabled / StreamGuardKB 是 Responses 流式保险丝:\ninstructions+tools 合计超阈值(KB)的流式请求改非流式上游并合成 SSE",
+                    "type": "boolean"
+                },
+                "streamGuardKB": {
+                    "type": "integer"
                }
            }
        },
@@ -6614,6 +6659,17 @@
                }
            }
        },
+        "internal_api.itemsResponse-oci-portal_internal_service_AggregatedModel": {
+            "type": "object",
+            "properties": {
+                "items": {
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/oci-portal_internal_service.AggregatedModel"
+                    }
+                }
+            }
+        },
        "internal_api.itemsResponse-oci-portal_internal_service_NotifyChannelView": {
            "type": "object",
            "properties": {
@@ -9351,6 +9407,17 @@
                }
            }
        },
+        "oci-portal_internal_service.AggregatedModel": {
+            "type": "object",
+            "properties": {
+                "capability": {
+                    "type": "string"
+                },
+                "name": {
+                    "type": "string"
+                }
+            }
+        },
        "oci-portal_internal_service.AuditEventsView": {
            "type": "object",
            "properties": {
@@ -49,7 +49,22 @@ definitions:
  internal_api.aiSettingsResponse:
    properties:
      filterDeprecated:
+        description: FilterDeprecated 开启后已宣布弃用(即使未退役)的模型从列表与路由中排除
        type: boolean
+      grokWebSearch:
+        description: |-
+          GrokWebSearch / GrokXSearch 是 xai. 模型服务端搜索工具默认注入开关;
+          请求 tools 已包含同名工具时不覆盖
+        type: boolean
+      grokXSearch:
+        type: boolean
+      streamGuardEnabled:
+        description: |-
+          StreamGuardEnabled / StreamGuardKB 是 Responses 流式保险丝:
+          instructions+tools 合计超阈值(KB)的流式请求改非流式上游并合成 SSE
+        type: boolean
+      streamGuardKB:
+        type: integer
    type: object
  internal_api.attachBootVolumeRequest:
    properties:
@@ -427,6 +442,13 @@ definitions:
          $ref: '#/definitions/oci-portal_internal_model.UserIdentity'
        type: array
    type: object
+  internal_api.itemsResponse-oci-portal_internal_service_AggregatedModel:
+    properties:
+      items:
+        items:
+          $ref: '#/definitions/oci-portal_internal_service.AggregatedModel'
+        type: array
+    type: object
  internal_api.itemsResponse-oci-portal_internal_service_NotifyChannelView:
    properties:
      items:
@@ -2232,6 +2254,13 @@ definitions:
        description: 卷本身的名称（attachment 名是自动生成的）
        type: string
    type: object
+  oci-portal_internal_service.AggregatedModel:
+    properties:
+      capability:
+        type: string
+      name:
+        type: string
+    type: object
  oci-portal_internal_service.AuditEventsView:
    properties:
      cursor:
@@ -3135,6 +3164,18 @@ paths:
      summary: AI 调用日志列表
      tags:
      - AI 管理
+  /api/v1/ai-model-catalog:
+    get:
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/internal_api.itemsResponse-oci-portal_internal_service_AggregatedModel'
+      security:
+      - BearerAuth: []
+      summary: 聚合模型目录
+      tags:
+      - AI 管理
  /api/v1/ai-models:
    get:
      responses:
@@ -3161,7 +3202,7 @@ paths:
      - AI 管理
    put:
      parameters:
-      - description: 开启后已宣布弃用(即使未退役)的模型从列表与路由中排除
+      - description: 全量提交;保险丝阈值限 1..1024 KB
        in: body
        name: body
        required: true
@@ -3172,6 +3213,12 @@ paths:
          description: OK
          schema:
            $ref: '#/definitions/internal_api.aiSettingsResponse'
+        "400":
+          description: Bad Request
+          schema:
+            additionalProperties:
+              type: string
+            type: object
      security:
      - BearerAuth: []
      summary: 更新 AI 网关全局设置