跳到主要内容

图灵 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 响应
X-Turing-Memory-*托管记忆本轮的读取和写入结果，共 6 个头，见托管记忆响应头开启 turing_options.memory 的 Chat Completions 响应，含流式

一次典型的非流式响应：

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.1-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。

托管记忆响应头​

Chat Completions 请求开启 turing_options.memory 后，响应会带上下列头，说明本轮是否使用和写入了记忆。响应体和 SSE 事件的格式不变，不读取这些头的客户端不受影响。开启方式见 LTM 接入方式。

Header说明
X-Turing-Memory-Read-Statusused：本轮使用了记忆；empty：没有相关记忆，属于正常状态；degraded：本轮没有使用记忆，回答照常返回
X-Turing-Memory-Capture-Statusaccepted：本轮已写入为 Event，记忆由后台异步派生；skipped：本轮不写入；failed：写入没有成功；conflict：同一轮次已用不同内容写入过，本次没有覆盖；pending：流式响应，写入在输出结束后进行
X-Turing-Memory-Event-Id写入的 Event ID，仅在 accepted 时返回
X-Turing-Memory-Turn-Id本轮的记忆轮次 ID，执行了记忆读取时返回
X-Turing-Memory-Evidence-Source记忆证据来源，执行了记忆读取时返回，目前固定为 computed
X-Turing-Memory-Reason本轮没有使用记忆或没有写入时的原因码，例如 fallback_enabled（请求配置了 fallback，本次整体不使用记忆）、ltm_unavailable（记忆读取或写入未能完成）、caller_tool_call（模型返回的是工具调用，本轮不写入）。其他取值用于排障，请按原样记录
信息
  • 只有三类错误会让请求失败：turing_options.memory 格式无效（code 1004）、当前凭据无权使用该 client 的记忆（code 1308）、Space 不存在或不属于当前 client 与环境（code 1751）。其他记忆故障不会中断回答，只会体现在上述响应头中，建议监控 degraded、failed 和 X-Turing-Memory-Reason。
  • 流式响应同样返回：这些头在输出开始前发送，此时还没有写入，因此 X-Turing-Memory-Capture-Status 为 pending（记忆被旁路时为 skipped）。
  • 浏览器可读：这些头均已加入 CORS expose_headers。

错误码含义详见 错误码。

请求头（客户端设置）​

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​