使用统计
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 提供商收取的实际成本
注意: upstream_inference_cost
字段仅适用于 BYOK(自带密钥)请求。
性能影响
启用使用统计将为最后的响应增加几百毫秒,因为 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'])
import OpenAI from 'openai';
const openai = new OpenAI({
baseURL: 'https://www.openroute.cn/api/v1',
apiKey: '<OPENROUTE_API_KEY>',
});
async function getResponseWithUsage() {
const response = await openai.chat.completions.create({
model: 'anthropic/claude-3-opus',
messages: [
{
role: 'user',
content: '法国的首都是什么?',
},
],
extra_body: {
usage: {
include: true,
},
},
});
console.log('响应:', response.choices[0].message.content);
console.log('使用统计:', response.usage);
}
getResponseWithUsage();
带使用信息的流式处理
此示例显示如何在流式模式下处理使用信息:
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="")
import OpenAI from 'openai';
const openai = new OpenAI({
baseURL: 'https://www.openroute.cn/api/v1',
apiKey: '<OPENROUTE_API_KEY>',
});
async function chatCompletionWithUsage(messages) {
const response = await openai.chat.completions.create({
model: 'anthropic/claude-3-opus',
messages,
usage: {
include: true,
},
stream: true,
});
return response;
}
(async () => {
for await (const chunk of chatCompletionWithUsage([
{ role: 'user', content: '写一首关于巴黎的俳句。' },
])) {
if (chunk.usage) {
console.log('\n使用统计:');
console.log(`总 Token: ${chunk.usage.total_tokens}`);
console.log(`提示 Token: ${chunk.usage.prompt_tokens}`);
console.log(`完成 Token: ${chunk.usage.completion_tokens}`);
console.log(`成本: ${chunk.usage.cost} 积分`);
} else if (chunk.choices[0].delta.content) {
process.stdout.write(chunk.choices[0].delta.content);
}
}
})();
Last updated on