使用统计
OpenRoute API 提供内置的使用统计功能，允许您在不进行额外 API 调用的情况下跟踪 AI 模型使用情况。此功能直接在您的 API 响应中提供有关 token 计数、成本和缓存状态的详细信息。
使用信息
启用后，API 将返回详细的使用信息，包括：
- 使用模型原生分词器计算的提示和完成 token 计数
- 以积分计算的成本
- 推理 token 计数（如果适用）
- 缓存 token 计数（如果可用）
此信息包含在流式响应的最后一条 SSE 消息中，或非流式请求的完整响应中。
启用使用统计
您可以通过在请求中包含 usage 参数来启用使用统计：
{
"model": "your-model",
"messages": [],
"usage": {
"include": true
}
}响应格式
启用使用统计后，响应将包含带有详细 token 信息的 usage 对象：
{
"object": "chat.completion.chunk",
"usage": {
"completion_tokens": 2,
"completion_tokens_details": {
"reasoning_tokens": 0
},
"cost": 0.95,
"cost_details": {
"upstream_inference_cost": 19
},
"prompt_tokens": 194,
"prompt_tokens_details": {
"cached_tokens": 0,
"audio_tokens": 0
},
"total_tokens": 196
}
}cached_tokens 是从缓存中_读取_的 token 数量。目前，我们不支持检索_写入_缓存的 token 数量。
成本明细
使用响应包括详细的成本信息：
cost：向您的账户收取的总金额cost_details.upstream_inference_cost：上游 AI 提供商收取的实际成本
性能影响
启用使用统计将为最后的响应增加几百毫秒，因为 API 需要计算 token 计数和成本。这仅影响最终消息，不会影响整体流式性能。
优势
- 效率：无需进行单独的 API 调用即可获取使用信息
- 准确性：使用模型的原生分词器计算 token 计数
- 透明度：实时跟踪成本和缓存 token 使用情况
- 详细分解：分别计算提示、完成、推理和缓存 token 的计数
最佳实践
- 当您需要监控 token 消耗或成本时启用使用跟踪
- 考虑启用使用统计时最终响应的轻微延迟
- 考虑在开发中实施使用跟踪，以便在生产前优化 token 使用
- 使用缓存 token 信息来优化应用程序的性能
替代方案：通过生成 ID 获取使用情况
您还可以通过使用 API 调用返回的生成 ID 异步检索使用信息。当您想在完成完成后获取使用统计信息或需要审计历史使用情况时，这特别有用。
要使用此方法：
- 正常进行聊天完成请求
- 注意响应中的
id字段 - 使用该 ID 通过
/generation端点获取使用信息
有关此方法的更多详细信息，请参阅获取生成文档。
示例
带 Token 跟踪的基本使用
import requests
import json
url = "https://www.openroute.cn/api/v1/chat/completions"
headers = {
"Authorization": f"Bearer <OPENROUTE_API_KEY>",
"Content-Type": "application/json"
}
payload = {
"model": "anthropic/claude-3-opus",
"messages": [
{"role": "user", "content": "法国的首都是什么？"}
],
"usage": {
"include": True
}
}
response = requests.post(url, headers=headers, data=json.dumps(payload))
print("响应:", response.json()['choices'][0]['message']['content'])
print("使用统计:", response.json()['usage'])带使用信息的流式处理
此示例显示如何在流式模式下处理使用信息：
from openai import OpenAI
client = OpenAI(
base_url="https://www.openroute.cn/api/v1",
api_key="<OPENROUTE_API_KEY>",
)
def chat_completion_with_usage(messages):
response = client.chat.completions.create(
model="anthropic/claude-3-opus",
messages=messages,
usage={
"include": True
},
stream=True
)
return response
for chunk in chat_completion_with_usage([
{"role": "user", "content": "写一首关于巴黎的俳句。"}
]):
if hasattr(chunk, 'usage'):
if hasattr(chunk.usage, 'total_tokens'):
print(f"\n使用统计:")
print(f"总 Token: {chunk.usage.total_tokens}")
print(f"提示 Token: {chunk.usage.prompt_tokens}")
print(f"完成 Token: {chunk.usage.completion_tokens}")
print(f"成本: {chunk.usage.cost} 积分")
elif chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")