文档中心

Appearance

✨费用中心控制台

记录请求标识和链路信息用于排查 ​

当 API 请求失败、响应变慢或结果需要复核时，先记录响应体中的 id 和响应头中的 traceresponse。如果您的客户端、网关或业务服务已经接入链路追踪，也可以在请求中发送 traceparent，再把请求中的 traceparent 与响应中的 traceresponse 一起保存。

这些值用于把业务侧记录、API 响应和平台侧请求链路对应起来；它们不表示模型版本、后端配置版本，也不是防篡改签名。

场景建议记录
普通失败、慢请求或结果复核响应体 id、响应头 traceresponse、请求时间、HTTP 状态码、耗时
已接入 OpenTelemetry 或其他链路追踪系统请求头 traceparent、响应头 traceresponse、响应体 id
只做业务日志关联响应体 id，以及业务侧自己的请求编号

获取响应头和响应体 ​

使用 --dump-header 保存响应头，使用 --output 保存响应体。不要把带有 Authorization 请求头的 verbose 日志直接发送给他人。

先按您使用的终端选择命令。以下示例都会把响应头写入 response-headers.txt，把响应体写入 response.json。

在 macOS、Linux、WSL 或 Git Bash 中保存响应 ​

以下命令适用于 bash/zsh 等 POSIX 风格 Shell：

language-shell
curl --silent --show-error \
  --dump-header response-headers.txt \
  --output response.json \
  --url "https://cloud.infini-ai.com/maas/v1/chat/completions" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "model": "kimi-k2.6",
    "messages": [
      {
        "role": "user",
        "content": "你是谁"
      }
    ]
  }'

在 PowerShell 中保存响应 ​

PowerShell 中请使用 curl.exe，避免把命令解析为 PowerShell 的 curl 别名。

language-powershell
$body = @'
{
  "model": "kimi-k2.6",
  "messages": [
    {
      "role": "user",
      "content": "你是谁"
    }
  ]
}
'@

curl.exe --silent --show-error `
  --dump-header response-headers.txt `
  --output response.json `
  --url "https://cloud.infini-ai.com/maas/v1/chat/completions" `
  --header "Authorization: Bearer $env:API_KEY" `
  --header "Content-Type: application/json" `
  --data-raw $body

在 CMD 中保存响应 ​

CMD 中使用 %API_KEY% 读取环境变量，并用 ^ 换行：

language-cmd
curl.exe --silent --show-error ^
  --dump-header response-headers.txt ^
  --output response.json ^
  --url "https://cloud.infini-ai.com/maas/v1/chat/completions" ^
  --header "Authorization: Bearer %API_KEY%" ^
  --header "Content-Type: application/json" ^
  --data-raw "{\"model\":\"kimi-k2.6\",\"messages\":[{\"role\":\"user\",\"content\":\"你是谁\"}]}"

执行成功后，终端通常不会显示响应内容；响应头已写入 response-headers.txt，响应体已写入 response.json。如果请求返回错误，也先保留这两个文件。排查时需要把请求标识、错误响应和请求时间放在一起看。

可选：发送 traceparent 关联业务侧链路 ​

如果您的客户端、网关或业务服务已经接入 OpenTelemetry 或其他链路追踪系统，可以在请求中发送 traceparent。平台返回的 traceresponse 会携带平台侧处理该请求时生成的链路信息，便于把业务侧调用和平台侧请求链路对应起来。

发送 traceparent 不会把 traceresponse 改成客户端可控的请求编号。平台仍会为本次请求生成自己的服务端 span ID，并在 traceresponse 中返回。排查时请同时提供响应体 id，因为它是面向 API 响应的请求标识。

信息

不要在不相关的请求中反复发送完全相同的 traceparent。这样通常不会导致请求失败，但会让多次请求看起来像同一个客户端 span 的子请求，影响链路因果关系和后续排查。建议为每次 API 请求生成新的 span ID；只有同一次业务操作、会话步骤或 agent 运行中的相关调用，才复用同一个 trace-id。

手动测试时，可以在 macOS、Linux、WSL 或 Git Bash 中生成一个 traceparent，并把它加入请求头：

language-shell
TRACEPARENT="00-$(openssl rand -hex 16)-$(openssl rand -hex 8)-01"

curl --silent --show-error \
  --dump-header response-headers.txt \
  --output response.json \
  --url "https://cloud.infini-ai.com/maas/v1/chat/completions" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --header "traceparent: $TRACEPARENT" \
  --data-raw '{
    "model": "kimi-k2.6",
    "messages": [
      {
        "role": "user",
        "content": "你是谁"
      }
    ]
  }'

请求中发送：

language-text
traceparent: 00-8199170e33389e6687df144d9dbc19f6-a902ed3cf7e1acac-01

响应中返回：

language-text
traceresponse: 00-8199170e33389e6687df144d9dbc19f6-c453f38a50b3eb3d-01

如果两者的第二段 trace-id 相同，表示平台沿用了该请求的链路上下文；第三段通常不同，因为平台会生成自己的服务端 span ID。

使用 OpenAI 兼容 SDK 时，可以通过 extra_headers 发送 traceparent：

language-python
from openai import OpenAI
import secrets


def generate_traceparent():
    return f"00-{secrets.token_hex(16)}-{secrets.token_hex(8)}-01"


client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://cloud.infini-ai.com/maas/v1",
)

traceparent = generate_traceparent()

response = client.chat.completions.create(
    model="kimi-k2.6",
    messages=[{"role": "user", "content": "你是谁"}],
    extra_headers={"traceparent": traceparent},
)

print("traceparent:", traceparent)
print("response id:", response.id)

记录 traceresponse ​

在 response-headers.txt 中查找 traceresponse：

language-text
traceresponse: 00-2605091906134c4421797807457ee045-fd3bf3deadfe4cdc-01

traceresponse 通常采用 00-＜trace-id＞-＜platform-span-id＞-＜trace-flags＞ 的格式。联系技术支持时提供该值，平台可据此定位对应的后端请求链路。它是链路上下文信息，不是模型输出的唯一凭证；请同时记录响应体中的 id。

记录响应 id ​

在 response.json 中记录 id、model 和 usage：

language-json
{
  "id": "15b1845672c7410db3c3157ca8554dff",
  "object": "chat.completion",
  "model": "kimi-k2.6",
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 116,
    "total_tokens": 125
  }
}

将 id 与请求时间、模型 ID、HTTP 状态码、耗时和 Token 用量一起写入业务日志。这样可以在排查时把业务侧记录、API 响应和平台侧请求链路对应起来。

提供排查信息 ​

联系技术支持前，先整理以下信息：

  • 请求时间和时区。
  • 请求端点和模型 ID。
  • HTTP 状态码和错误响应。
  • 响应头中的 traceresponse。
  • 如果请求中发送了 traceparent，同时提供该请求头的值。
  • 响应体中的 id。
  • 客户端、SDK 或工具名称。
  • 已脱敏的请求参数。

不要发送 API Key、完整密钥日志或包含敏感信息的原始输入。如果已经把密钥写入日志、截图或工单，请立即停用并重新创建 API Key。