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

先决条件

本指南假定读者熟悉以下概念：

聊天模型

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

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

%pip install -qU langchain-anthropic langchain-openai

关于使用 OpenAI 进行流式传输的说明

OpenAI 的聊天补全 API 默认不会流式传输令牌使用统计信息（参见 API 参考此处）。在使用 ChatOpenAI 或 AzureChatOpenAI 进行流式处理时，若要恢复令牌计数，请将 stream_usage=True 设置为本指南中所示。

使用 LangSmith

您可以使用 LangSmith 来帮助跟踪您的大语言模型应用中的令牌使用情况。参见 LangSmith 快速入门指南。

使用AIMessage.usage_metadata

许多模型提供者会在聊天生成响应中返回令牌使用信息。如果可用，此信息将包含在相应模型生成的 AIMessage 对象中。

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

Examples:

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 实例化时，也可以设置此属性。

笔记

默认情况下，流中的最后一个消息块将在消息的 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 来启用流式传输令牌使用。这在将聊天模型集成到 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.'

令牌使用情况在聊天模型的负载中对应的 LangSmith 跟踪中也可见。

使用回调

需要 langchain-core>=0.3.49

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

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

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

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

要通过配置跟踪令牌使用情况，请实例化一个 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 参考：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}}}

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

您也可以使用 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 参考：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}}}

这两种方法都可以汇总对每个模型的多次调用中的令牌使用情况。例如，您可以在一个代理中使用它来跟踪对一个模型的重复调用中的令牌使用情况：

%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​

使用回调​

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

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

下一步​