跳到主要内容

图灵 Headers 协议

图灵平台在标准 HTTP 头之外，约定了一组 X-Turing-* / x-turing-* 头：响应头回传本次调用的追踪 ID、实际路由结果与耗时；请求头用于主动排查、打标与串联调用链。本页是这些头的权威参考——其它页面（请求追踪、超时、重试与 Fallback）只介绍各自场景下的用法，具体定义以此处为准。

响应头（平台返回）​

Header说明适用范围
X-Turing-Trace-Id图灵平台的请求追踪 ID，用于回查日志与计费每个响应
X-Turing-Process-Time平台侧处理耗时（毫秒）每个响应
x-turing-model-id实际服务本次请求的模型 ID（fallback / auto 时尤其有用）非流式 LLM 响应
x-turing-retries本次请求实际发生的重试次数非流式 LLM 响应
x-turing-fallbacks本次请求实际发生的 fallback 切换次数非流式 LLM 响应

一次典型的非流式响应：

curl -i $TURING_BASE_URL/chat/completions \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "turing/gpt-4.1",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

# 响应 Headers：
# x-turing-trace-id:     xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# x-turing-process-time: 812.34
# x-turing-model-id:     gpt-4.1
# x-turing-retries:      0
# x-turing-fallbacks:    0

用 X-Turing-Trace-Id 排查问题、回查计费的完整流程见 请求追踪。

响应观测头：实际模型 / 重试 / Fallback​

配置了 fallback / 重试后，x-turing-model-id / x-turing-retries / x-turing-fallbacks 让你在客户端确认「真正服务你的是哪个模型、发生了几次重试和 fallback」：

Header说明
x-turing-model-id实际服务本次请求的模型 ID。配置了 fallbacks（尤其是 auto）时，据此确认最终落到哪个模型
x-turing-retries本次请求实际发生的重试次数（对应 turing_options.max_retries）
x-turing-fallbacks本次请求实际发生的 fallback 切换次数
from openai import OpenAI

client = OpenAI()

response = client.chat.completions.with_raw_response.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "Hello!"}],
    turing_options={
        "max_retries": 2,
        "fallbacks": "auto",
    },
)

print("served by:", response.headers.get("x-turing-model-id"))
print("retries:  ", response.headers.get("x-turing-retries"))
print("fallbacks:", response.headers.get("x-turing-fallbacks"))

completion = response.parse()
信息
  • 仅非流式：流式（stream=True）响应通过 SSE 分片传输，不携带这三个头。
  • 错误响应也有：fallback 全部耗尽而报错时，这三个头依然会返回——此时正是最需要它们来判断链路走到哪一步的时候。
  • 浏览器可读：三个头均已加入 CORS expose_headers，前端可直接通过 response.headers.get(...) 读取。

配置项（max_retries / fallbacks）详见 超时、重试与 Fallback。

请求头（客户端设置）​

Header说明
AuthorizationBearer <API_KEY>，所有请求必填
X-Client-Request-Id客户端主动生成的请求 ID。请求失败 / 无响应时仍可凭它排查（见 请求追踪）
X-Turing-Tags请求打标，JSON 字符串。用于用量归类与来源标识
X-Turing-Trace-Id（可选） 主动传入以复用 trace id、把同一条业务链路上的多次调用串联到一个 ID。仅在 10 分钟新鲜期内有效，过期会被忽略并自动新生成
import json
from openai import OpenAI

client = OpenAI()

completion = client.chat.completions.create(
    model="turing/gpt-4.1",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_headers={
        "X-Client-Request-Id": "req-20260715-abcdef",
        "X-Turing-Tags": json.dumps({"team": "growth", "scene": "summarizer"}),
    },
)

See also​