如何追踪 ChatModels 的 Token 使用量

先决条件

本指南假设您已熟悉以下概念：

Chat models

追踪 token 使用量以计算成本是部署应用程序的重要组成部分。本指南将介绍如何从您的 LangChain 模型调用中获取这些信息。

本指南需要 langchain-anthropic 和 langchain-openai >= 0.3.11。

%pip install -qU langchain-anthropic langchain-openai

关于 OpenAI 流式传输的注意事项

OpenAI 的 Chat Completions API 默认不流式传输 token 使用情况统计信息（请参阅此处的 API 参考文档 here）。要在使用 ChatOpenAI 或 AzureChatOpenAI 进行流式传输时恢复 token 计数，请将 stream_usage 设置为 True，如本指南所示。

使用 LangSmith

您可以使用 LangSmith 来帮助跟踪 LLM 应用中的 token 使用量。请参阅 LangSmith 快速入门指南。

使用 AIMessage.usage_metadata

许多模型提供商会在聊天生成响应中包含 token 使用信息。如果可用，这些信息将包含在相应模型生成的 AIMessage 对象上。

LangChain 的 AIMessage 对象包含一个 usage_metadata 属性。当填充时，此属性将是一个 UsageMetadata 字典，包含标准键（例如 "input_tokens" 和 "output_tokens"）。它们还将包含关于缓存的 token 使用量和来自多模态数据的 token 的信息。

示例：

OpenAI:

from langchain.chat_models import init_chat_model

llm = init_chat_model(model="gpt-4o-mini")
openai_response = llm.invoke("hello")
openai_response.usage_metadata

API Reference:init_chat_model

{'input_tokens': 8, 'output_tokens': 9, 'total_tokens': 17}

Anthropic:

from langchain_anthropic import ChatAnthropic

llm = ChatAnthropic(model="claude-3-haiku-20240307")
anthropic_response = llm.invoke("hello")
anthropic_response.usage_metadata

API Reference:ChatAnthropic

{'input_tokens': 8, 'output_tokens': 12, 'total_tokens': 20}

流式传输

一些提供商在流式传输的上下文中支持令牌计数元数据。

OpenAI

例如，OpenAI 将在流的末尾返回一个消息块，其中包含令牌使用信息。此行为受 langchain-openai >= 0.1.9 支持，可以通过设置 stream_usage=True 来启用。设置 ChatOpenAI 实例时也可以设置此属性。

note

默认情况下，流中的最后一个消息块将在消息的 response_metadata 属性中包含一个 "finish_reason"。如果我们启用流式传输模式下的令牌使用计数，则会在流的末尾添加一个包含元数据的附加块，以便 "finish_reason" 出现在倒数第二个消息块上。

llm = init_chat_model(model="gpt-4o-mini")

aggregate = None
for chunk in llm.stream("hello", stream_usage=True):
    print(chunk)
    aggregate = chunk if aggregate is None else aggregate + chunk

content='' id='run-adb20c31-60c7-43a2-99b2-d4a53ca5f623'
content='Hello' id='run-adb20c31-60c7-43a2-99b2-d4a53ca5f623'
content='!' id='run-adb20c31-60c7-43a2-99b2-d4a53ca5f623'
content=' How' id='run-adb20c31-60c7-43a2-99b2-d4a53ca5f623'
content=' can' id='run-adb20c31-60c7-43a2-99b2-d4a53ca5f623'
content=' I' id='run-adb20c31-60c7-43a2-99b2-d4a53ca5f623'
content=' assist' id='run-adb20c31-60c7-43a2-99b2-d4a53ca5f623'
content=' you' id='run-adb20c31-60c7-43a2-99b2-d4a53ca5f623'
content=' today' id='run-adb20c31-60c7-43a2-99b2-d4a53ca5f623'
content='?' id='run-adb20c31-60c7-43a2-99b2-d4a53ca5f623'
content='' response_metadata={'finish_reason': 'stop', 'model_name': 'gpt-4o-mini'} id='run-adb20c31-60c7-43a2-99b2-d4a53ca5f623'
content='' id='run-adb20c31-60c7-43a2-99b2-d4a53ca5f623' usage_metadata={'input_tokens': 8, 'output_tokens': 9, 'total_tokens': 17}

请注意，使用情况元数据将包含在各个消息块的总和中：

print(aggregate.content)
print(aggregate.usage_metadata)

Hello! How can I assist you today?
{'input_tokens': 8, 'output_tokens': 9, 'total_tokens': 17}

要禁用 OpenAI 的流式令牌计数，请将 stream_usage 设置为 False，或者将其从参数中省略：

aggregate = None
for chunk in llm.stream("hello"):
    print(chunk)

content='' id='run-8e758550-94b0-4cca-a298-57482793c25d'
content='Hello' id='run-8e758550-94b0-4cca-a298-57482793c25d'
content='!' id='run-8e758550-94b0-4cca-a298-57482793c25d'
content=' How' id='run-8e758550-94b0-4cca-a298-57482793c25d'
content=' can' id='run-8e758550-94b0-4cca-a298-57482793c25d'
content=' I' id='run-8e758550-94b0-4cca-a298-57482793c25d'
content=' assist' id='run-8e758550-94b0-4cca-a298-57482793c25d'
content=' you' id='run-8e758550-94b0-4cca-a298-57482793c25d'
content=' today' id='run-8e758550-94b0-4cca-a298-57482793c25d'
content='?' id='run-8e758550-94b0-4cca-a298-57482793c25d'
content='' response_metadata={'finish_reason': 'stop', 'model_name': 'gpt-4o-mini'} id='run-8e758550-94b0-4cca-a298-57482793c25d'

您还可以通过在实例化聊天模型时设置 stream_usage 来启用流式 token 使用。当将聊天模型集成到 LangChain 链中时，这会非常有用：可以在流式传输中间步骤或使用 LangSmith 等跟踪软件 LangSmith 时监视模型使用情况的元数据。

请看下面的示例，在此示例中，我们以结构化形式返回输出到期望的模式，但仍然可以观察到从中间步骤流式传输的 token 使用情况。

from pydantic import BaseModel, Field


class Joke(BaseModel):
    """Joke to tell user."""

    setup: str = Field(description="question to set up a joke")
    punchline: str = Field(description="answer to resolve the joke")


llm = init_chat_model(
    model="gpt-4o-mini",
    stream_usage=True,
)
# Under the hood, .with_structured_output binds tools to the
# chat model and appends a parser.
structured_llm = llm.with_structured_output(Joke)

async for event in structured_llm.astream_events("Tell me a joke"):
    if event["event"] == "on_chat_model_end":
        print(f'Token usage: {event["data"]["output"].usage_metadata}\n')
    elif event["event"] == "on_chain_end" and event["name"] == "RunnableSequence":
        print(event["data"]["output"])
    else:
        pass

Token usage: {'input_tokens': 79, 'output_tokens': 23, 'total_tokens': 102}

setup='Why was the math book sad?' punchline='Because it had too many problems.'

Token 用量在聊天模型负载的相应 LangSmith 追踪中也可查到。

使用回调

需要 langchain-core>=0.3.49

LangChain 实现了一个回调处理器和上下文管理器，它将跟踪返回 usage_metadata 的任何聊天模型的调用中的 token 使用情况。

还有一些特定于 API 的回调上下文管理器，它们维护不同模型的定价，从而允许实时成本估算。它们目前仅为 OpenAI API 和 Bedrock Anthropic API 实现，并在 langchain-community 中提供：

下面，我们将演示通用的 usage metadata 回调管理器。我们可以通过配置或上下文管理器来跟踪 token 使用情况。

通过配置跟踪 token 使用情况

要通过配置跟踪 token 使用情况，请实例化一个 UsageMetadataCallbackHandler 并将其传递到配置中：

from langchain.chat_models import init_chat_model
from langchain_core.callbacks import UsageMetadataCallbackHandler

llm_1 = init_chat_model(model="openai:gpt-4o-mini")
llm_2 = init_chat_model(model="anthropic:claude-3-5-haiku-latest")

callback = UsageMetadataCallbackHandler()
result_1 = llm_1.invoke("Hello", config={"callbacks": [callback]})
result_2 = llm_2.invoke("Hello", config={"callbacks": [callback]})
callback.usage_metadata

API Reference:init_chat_model | UsageMetadataCallbackHandler

{'gpt-4o-mini-2024-07-18': {'input_tokens': 8,
  'output_tokens': 10,
  'total_tokens': 18,
  'input_token_details': {'audio': 0, 'cache_read': 0},
  'output_token_details': {'audio': 0, 'reasoning': 0}},
 'claude-3-5-haiku-20241022': {'input_tokens': 8,
  'output_tokens': 21,
  'total_tokens': 29,
  'input_token_details': {'cache_read': 0, 'cache_creation': 0}}}

使用上下文管理器追踪 token 用量

您还可以使用 get_usage_metadata_callback 来创建一个上下文管理器，并在其中聚合用量元数据：

from langchain.chat_models import init_chat_model
from langchain_core.callbacks import get_usage_metadata_callback

llm_1 = init_chat_model(model="openai:gpt-4o-mini")
llm_2 = init_chat_model(model="anthropic:claude-3-5-haiku-latest")

with get_usage_metadata_callback() as cb:
    llm_1.invoke("Hello")
    llm_2.invoke("Hello")
    print(cb.usage_metadata)

API Reference:init_chat_model | get_usage_metadata_callback

{'gpt-4o-mini-2024-07-18': {'input_tokens': 8, 'output_tokens': 10, 'total_tokens': 18, 'input_token_details': {'audio': 0, 'cache_read': 0}, 'output_token_details': {'audio': 0, 'reasoning': 0}}, 'claude-3-5-haiku-20241022': {'input_tokens': 8, 'output_tokens': 21, 'total_tokens': 29, 'input_token_details': {'cache_read': 0, 'cache_creation': 0}}}

这两种方法都可以汇总多次调用每个模型的 token 用量。例如，您可以在 agent 中使用它来跟踪对单个模型的重复调用中的 token 用量：

%pip install -qU langgraph

from langgraph.prebuilt import create_react_agent


# Create a tool
def get_weather(location: str) -> str:
    """Get the weather at a location."""
    return "It's sunny."


callback = UsageMetadataCallbackHandler()

tools = [get_weather]
agent = create_react_agent("openai:gpt-4o-mini", tools)
for step in agent.stream(
    {"messages": [{"role": "user", "content": "What's the weather in Boston?"}]},
    stream_mode="values",
    config={"callbacks": [callback]},
):
    step["messages"][-1].pretty_print()


print(f"\nTotal usage: {callback.usage_metadata}")

API Reference:create_react_agent

================================[1m Human Message [0m=================================

What's the weather in Boston?
==================================[1m Ai Message [0m==================================
Tool Calls:
  get_weather (call_izMdhUYpp9Vhx7DTNAiybzGa)
 Call ID: call_izMdhUYpp9Vhx7DTNAiybzGa
  Args:
    location: Boston
=================================[1m Tool Message [0m=================================
Name: get_weather

It's sunny.
==================================[1m Ai Message [0m==================================

The weather in Boston is sunny.

Total usage: {'gpt-4o-mini-2024-07-18': {'input_token_details': {'audio': 0, 'cache_read': 0}, 'input_tokens': 125, 'total_tokens': 149, 'output_tokens': 24, 'output_token_details': {'audio': 0, 'reasoning': 0}}}

后续步骤

您现在已经看到了跟踪受支持的提供商的 token 使用量的几个示例。

接下来，请查看本节中有关聊天模型的其他操作指南，例如如何让模型返回结构化输出或如何为聊天模型添加缓存。

使用 LangSmith​

使用 AIMessage.usage_metadata​

流式传输​

OpenAI​

使用回调​

通过配置跟踪 token 使用情况​

使用上下文管理器追踪 token 用量​

后续步骤​