如何在 ChatModels 中跟踪令牌使用情况

前置条件

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

聊天模型

跟踪 token 使用情况以计算成本是将应用投入生产的重要环节。本指南将介绍如何从您的 LangChain 模型调用中获取此信息。

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

%pip install -qU langchain-anthropic langchain-openai

关于与 OpenAI 流式传输的说明

OpenAI 的 Chat Completions API 默认不流式传输令牌使用统计信息（参见 API 参考此处）。当使用 ChatOpenAI 或 AzureChatOpenAI 进行流式传输时，若要恢复令牌计数，请按照本指南将 stream_usage=True 设置为相应值。

使用 LangSmith

您可以使用 LangSmith 来跟踪 LLM 应用中的令牌使用情况。请参阅 LangSmith 快速入门指南。

使用 AIMessage.usage_metadata

多个模型提供商在聊天生成响应中返回令牌使用信息。当可用时，此信息将包含在相应模型生成的AIMessage对象上。

LangChain AIMessage 对象包含一个 usage_metadata 属性。当该属性被填充时，它将是一个 UsageMetadata 字典，具有标准键（例如 "input_tokens" 和 "output_tokens"）。它还将包含有关缓存令牌使用情况以及来自多模态数据的令牌的信息。

示例:

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 参考: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 参考:ChatAnthropic

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

流式传输

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

OpenAI

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

注意

默认情况下，流中的最后一条消息块将在消息的"finish_reason"属性中包含"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 Chains 中时，这非常有用：可以在流式传输中间步骤或使用如 LangSmith 等追踪软件时监控使用情况元数据。

查看以下示例，其中我们将输出结构化到所需的模式，但仍可观察到来自中间步骤的标记使用流。

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 的聊天模型调用中的令牌使用情况。

还有一些特定于 API 的回调上下文管理器，它们维护不同模型的定价信息，从而支持实时成本估算。目前这些功能仅在 OpenAI API 和 Bedrock Anthropic API 中实现，并在 langchain-community 版本中可用：

下面，我们演示通用用途的元数据回调管理器。我们可以通过配置或作为上下文管理器来跟踪令牌使用情况。

通过配置跟踪令牌使用情况

要跟踪通过配置使用的 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 参考:初始化聊天模型 |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}}}

使用上下文管理器跟踪令牌使用情况

您也可以使用 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 参考:初始化聊天模型 |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}}}

这两种方法都会聚合对每个模型进行多次调用的令牌使用情况。例如，您可以在智能体中使用它来跟踪对单个模型的重复调用中的令牌使用情况：

%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 参考: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}}}

下一步

您现在已看到一些如何跟踪受支持提供商的令牌使用情况的示例。

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

使用 LangSmith​

使用 AIMessage.usage_metadata​

流式传输​

OpenAI​

使用回调函数​

通过配置跟踪令牌使用情况​

使用上下文管理器跟踪令牌使用情况​

下一步​