xmAI Docs

中文

English

中文

English

Appearance

能力矩阵 ​

xmAI 网关将请求路由至多个 provider 家族。每个 channel 声明其所支持的能力。当请求所需的能力无法被目标 channel 表示时，网关会进行静默降级或返回 400 错误，并通过 X-Gateway-Degraded 响应头说明具体情况。

能力总览 ​

适配器server_tool_web_searchextended_thinkingcache_control_block_levelanthropic-beta 请求头
openai否否否剥离
azure-openai否否否剥离
anthropic是是是原样透传
bedrock是是是AWS 白名单过滤
vertex否是是透传
google否否否剥离

这些能力是什么？ ​

三个 boolean 能力标志全部是 Anthropic 原生协议功能，仅适用于 /v1/messages API 入口。只有客户端通过 Anthropic 协议发送请求时才会触发能力过滤 —— OpenAI /v1/chat/completions 入口没有等价概念，不受能力过滤影响。

能力标志对应的 Anthropic 协议功能请求 body 中的触发条件
server_tool_web_search服务端 Web 搜索工具tools: [{type: "web_search_20250305"}]
extended_thinking扩展思维链推理thinking: {type: "enabled"}
cache_control_block_level块级 Prompt Cachingmessages[].content[].cache_control 或 system[].cache_control

当网关将 Anthropic 协议入口的请求路由到非 Anthropic 上游（如 OpenAI、Google）时，这些功能无法被表示，会被静默丢弃。X-Gateway-Degraded 响应头会告知客户端具体丢失了什么。

anthropic-beta 请求头的工作机制 ​

Anthropic API 使用 anthropic-beta HTTP 请求头来启用实验性功能：

http
POST /v1/messages
anthropic-beta: web-search-2025-03-05,prompt-caching-scope-2026-01-05

每个 beta 值解锁一项特定功能。网关根据 channel 的上游 provider 类型，对此头做不同处理：

适配器anthropic-beta 处理方式
anthropic（直连）原样透传给 Anthropic API
bedrock仅透传 AWS 白名单（AWS_ALLOWED_ANTHROPIC_BETA）内的 beta 值，其余被剥离
vertex透传到 Vertex Anthropic 端点（有限 beta 支持）
openai / azure-openai / google忽略 — beta 头对非 Anthropic provider 无意义

Beta 过滤完全自动，无需管理员配置。Gateway 在运行时根据 adapter 类型自动处理，Admin UI 中没有 anthropic_beta_supported 配置项。

TIP

客户端无需关心 channel 支持哪些 beta。像直接调用 Anthropic API 一样在请求中附带 anthropic-beta header 即可。Gateway 会自动透传支持的 beta 值，静默剥离不支持的。

各字段详细说明 ​

  • server_tool_web_search：Anthropic 原生网络搜索工具。仅 anthropic 和 bedrock 能原生表示此工具。Vertex AI 的 Anthropic 兼容端点不暴露该工具。
  • extended_thinking：流式 budget_tokens / 扩展推理。anthropic、bedrock、vertex 均支持。
  • cache_control_block_level：块级 cache_control 提示缓存。anthropic、bedrock、vertex 均支持。
  • anthropic_beta_supported：声明该 channel 能向上游透传哪些 anthropic-beta 头值。Bedrock 要求模型在 Anthropic Converse API 的 beta 功能白名单内；Invoke API 路径不支持 beta 头。

X-Gateway-Degraded 响应头 ​

网关在跨家族转换过程中丢弃某项能力时，会在响应中设置 X-Gateway-Degraded 头。多个值以英文逗号分隔。

头值原因
server_tool_web_search_droppedtarget_family_cannot_represent_anthropic_native_web_search
extended_thinking_droppedtarget_family_cannot_represent_extended_thinking
prompt_caching_droppedtarget_family_cannot_represent_block_level_cache_control
server_tool_web_search_unavailableno_channel_declares_capability_for_model — 返回 HTTP 400

示例 ​

http
HTTP/1.1 200 OK
X-Gateway-Degraded: server_tool_web_search_dropped, prompt_caching_dropped

这表示请求包含了网络搜索工具和块级 cache_control，但所选 channel 无法表示这两项能力，均已被静默丢弃后转发。

客户端降级处理 ​

检测降级 ​

在每次包含高级 Anthropic 特性的请求响应中检查此头：

typescript
const response = await fetch('/v1/messages', { method: 'POST', body: JSON.stringify(payload) })
const degraded = response.headers.get('X-Gateway-Degraded')
if (degraded) {
  const dropped = degraded.split(',').map(s => s.trim())
  console.warn('网关降级了以下能力:', dropped)
}

重试策略 ​

如果应用必须依赖某项特定能力，建议：

  1. 每次响应都检查该头，尤其是涉及高级特性的请求。
  2. 不要盲目重试 — server_tool_web_search_unavailable 以 400 返回时，说明当前没有任何 channel 为该模型声明了网络搜索能力，重试结果相同。
  3. 对于软降级（*_dropped 类值），可考虑切换到其他模型，或向用户提示相关功能不可用。

用户界面提示 ​

将降级信息以简明语言呈现给用户。示例：

降级值建议提示文案
server_tool_web_search_dropped"所选模型不支持网络搜索，响应已在不使用搜索的情况下生成。"
extended_thinking_dropped"所选模型不支持扩展思考模式，该功能已被跳过。"
prompt_caching_dropped"提示缓存未生效，延迟和费用可能高于预期。"

管理员配置指南 ​

能力标志在管理后台的 Channels → 编辑 → Capabilities 中按 channel 声明。

能力标志说明 ​

标志说明
server_tool_web_search若上游端点支持 Anthropic 原生网络搜索工具，则启用
extended_thinking若上游端点支持 budget_tokens / 扩展推理，则启用
cache_control_block_level若上游端点支持块级 cache_control，则启用

示例：Bedrock channel 配置 ​

对于通过 Converse API 使用 Anthropic 模型的 Bedrock channel：

  • 启用 server_tool_web_search、extended_thinking、cache_control_block_level。
  • 启用 anthropic_beta_supported 前，确认目标模型在 Anthropic Converse API beta 功能白名单内。
  • Bedrock 的 Invoke API 路径不支持 beta 头 — Invoke channel 仅用于非 beta 工作负载，请配置独立 channel 分别处理。

跨家族常见陷阱 ​

场景陷阱
将 Anthropic 请求路由到 OpenAI channel三项能力均会被丢弃，X-Gateway-Degraded 将列出全部三个值。
Bedrock Invoke vs. ConverseInvoke 不支持 anthropic-beta，请根据实际路径配置能力，并为两种路径分别创建 channel。
Vertex 网络搜索Vertex 不支持 server_tool_web_search，不要在 Vertex channel 上启用此能力。
Google（原生 Gemini）三项能力均不支持。Gemini 的网络搜索使用不同机制，不在本矩阵范围内。

已知限制 ​

  • Vertex AI：即使是通过 Vertex 路由的 Anthropic 系列模型，server_tool_web_search 也不受支持。不要在 Vertex channel 上启用此能力。
  • Bedrock anthropic_beta 白名单：Beta 功能需要 Anthropic 在 Converse API 上明确将模型列入白名单。如需申请，请联系 Anthropic 或您的 AWS 客户经理。
  • 静默丢弃 vs. 硬错误：仅 server_tool_web_search_unavailable（无可用 channel）会触发 400 错误。其余降级均为静默丢弃并附带 X-Gateway-Degraded 头。应用需主动检查该头才能感知降级。
  • 无局部缓存回退：若 cache_control_block_level 被丢弃，请求中所有 cache_control 提示均不生效，不存在回退到会话级缓存的机制。

The Unified API for LLMs

© 2025 xmai.sg