跳到主要内容

请求追踪

当你需要图灵平台团队协助定位问题，或想回溯某一次请求的链路，都需要提供请求标识。平台提供两种：

Header方向说明
X-Turing-Trace-Id响应图灵平台返回的请求追踪 ID（被动获取）
X-Client-Request-Id请求客户端主动设置的请求 ID（主动设置）

两者可以并存——生产环境建议同时启用。

被动获取：从响应读取 Trace ID​

图灵平台会在每个响应的 Headers 中返回 X-Turing-Trace-Id。

SDK​

from openai import OpenAI

client = OpenAI()

# 使用 with_raw_response 获取原始响应
response = client.chat.completions.with_raw_response.create(
    model="turing/gpt-4.1",
    messages=[{"role": "user", "content": "Hello!"}]
)

# 从 Headers 中获取 Trace ID
trace_id = response.headers.get("x-turing-trace-id")
print(f"Trace ID: {trace_id}")

# 解析响应内容
completion = response.parse()

cURL​

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

主动设置：Client Request ID​

当请求失败（网络超时、连接中断）时，客户端可能根本没收到响应 Headers。这种情况下 Trace ID 无从获取；通过在请求时主动设置 X-Client-Request-Id，无论请求成功还是失败，都可以用这个 ID 排查问题。

SDK​

import uuid
from openai import OpenAI

client = OpenAI()

# 生成一个唯一的 Request ID
client_request_id = str(uuid.uuid4())
print(f"Client Request ID: {client_request_id}")

try:
    completion = client.chat.completions.create(
        model="turing/gpt-4.1",
        messages=[{"role": "user", "content": "Hello!"}],
        extra_headers={
            "X-Client-Request-Id": client_request_id
        }
    )
except Exception as e:
    # 即使请求失败，也可以用 client_request_id 排查
    print(f"请求失败，请联系图灵平台并提供 Client Request ID: {client_request_id}")
    raise

cURL​

# 先生成一个 UUID
CLIENT_REQUEST_ID=$(uuidgen)
echo "Client Request ID: $CLIENT_REQUEST_ID"

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

场景速查​

场景使用哪个 ID
请求成功，需要排查响应内容 / 计费响应 Headers 中的 X-Turing-Trace-Id
请求失败 / 超时 / 无响应请求时设置的 X-Client-Request-Id
长时间排查一段业务链路两个都带上，并写进业务日志

生产环境最佳实践​

建议在生产环境为每个请求都设置 X-Client-Request-Id，并把 两个 ID 都记录到业务日志，方便后续关联。

import uuid
import logging
from openai import OpenAI

client = OpenAI()
logger = logging.getLogger(__name__)

def call_llm(messages):
    client_request_id = str(uuid.uuid4())

    try:
        response = client.chat.completions.with_raw_response.create(
            model="turing/gpt-4.1",
            messages=messages,
            extra_headers={
                "X-Client-Request-Id": client_request_id
            }
        )

        trace_id = response.headers.get("x-turing-trace-id")
        logger.info(
            "LLM call success, client_request_id=%s, trace_id=%s",
            client_request_id, trace_id,
        )

        return response.parse()

    except Exception as e:
        logger.error(
            "LLM call failed, client_request_id=%s, error=%s",
            client_request_id, e,
        )
        raise

这样无论请求成功还是失败，都能通过日志中的 ID 快速定位问题。

See also​