使用 `LangChain` (Python 和 JS/TS) 进行追踪

LangSmith 与 LangChain (Python 和 JS) 无缝集成，LangChain 是用于构建 LLM 应用程序的流行开源框架。

安装

安装核心库和适用于 Python 和 JS 的 OpenAI 集成（我们在下面的代码片段中使用 OpenAI 集成）。

有关可用包的完整列表，请参阅 LangChain Python 文档和 LangChain JS 文档。

pip
yarn
npm
pnpm

pip install langchain_openai langchain_core

yarn add @langchain/openai @langchain/core

npm install @langchain/openai @langchain/core

pnpm add @langchain/openai @langchain/core

快速入门

1. 配置您的环境

Python
TypeScript

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=<your-api-key>
# This example uses OpenAI, but you can use any LLM provider of choice
export OPENAI_API_KEY=<your-openai-api-key>

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=<your-api-key>
# This example uses OpenAI, but you can use any LLM provider of choice
export OPENAI_API_KEY=<your-openai-api-key>

信息

如果您在非无服务器环境中使用 LangChain.js 和 LangSmith，我们还建议显式设置以下内容以减少延迟

export LANGCHAIN_CALLBACKS_BACKGROUND=true

如果您在无服务器环境中，我们建议反向设置以允许追踪在函数结束前完成

export LANGCHAIN_CALLBACKS_BACKGROUND=false

有关更多信息，请参阅此 LangChain.js 指南。

2. 记录追踪

无需额外代码即可将追踪记录到 LangSmith。像往常一样运行您的 LangChain 代码即可。

Python
TypeScript

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant. Please respond to the user's request only based on the given context."),
    ("user", "Question: {question}\nContext: {context}")
])
model = ChatOpenAI(model="gpt-4o-mini")
output_parser = StrOutputParser()

chain = prompt | model | output_parser

question = "Can you summarize this morning's meetings?"
context = "During this morning's meeting, we solved all world conflict."
chain.invoke({"question": question, "context": context})

import { ChatOpenAI } from "@langchain/openai";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { StringOutputParser } from "@langchain/core/output_parsers";

const prompt = ChatPromptTemplate.fromMessages([
  ["system", "You are a helpful assistant. Please respond to the user's request only based on the given context."],
  ["user", "Question: {question}\nContext: {context}"],
]);
const model = new ChatOpenAI({ modelName: "gpt-4o-mini" });
const outputParser = new StringOutputParser();

const chain = prompt.pipe(model).pipe(outputParser);

const question = "Can you summarize this morning's meetings?"
const context = "During this morning's meeting, we solved all world conflict."
await chain.invoke({ question: question, context: context });

3. 查看您的追踪

默认情况下，追踪将记录到名为 default 的项目。使用上述代码记录的追踪示例已公开，可在此处查看。

选择性追踪

上一节展示了如何通过设置单个环境变量来追踪应用程序中 LangChain 可运行对象的所有调用。虽然这是一种方便的入门方式，但您可能只想追踪应用程序的特定调用或部分。

在 Python 中有两种方法可以实现此目的：手动传入 LangChainTracer 实例（参考文档）作为回调，或使用 tracing_v2_enabled 上下文管理器（参考文档）。

在 JS/TS 中，您可以传入 LangChainTracer 实例（参考文档）作为回调。

Python
TypeScript

# You can configure a LangChainTracer instance to trace a specific invocation.
from langchain.callbacks.tracers import LangChainTracer

tracer = LangChainTracer()
chain.invoke({"question": "Am I using a callback?", "context": "I'm using a callback"}, config={"callbacks": [tracer]})

# LangChain Python also supports a context manager for tracing a specific block of code.
from langchain_core.tracers.context import tracing_v2_enabled
with tracing_v2_enabled():
  chain.invoke({"question": "Am I using a context manager?", "context": "I'm using a context manager"})

# This will NOT be traced (assuming LANGSMITH_TRACING is not set)
chain.invoke({"question": "Am I being traced?", "context": "I'm not being traced"})

// You can configure a LangChainTracer instance to trace a specific invocation.
import { LangChainTracer } from "@langchain/core/tracers/tracer_langchain";

const tracer = new LangChainTracer();
await chain.invoke(
{
  question: "Am I using a callback?",
  context: "I'm using a callback"
},
{ callbacks: [tracer] }
);

记录到特定项目

静态

正如追踪概念指南中所述，LangSmith 使用项目概念来对追踪进行分组。如果未指定，追踪器项目将设置为默认值。您可以设置 LANGSMITH_PROJECT 环境变量，为整个应用程序运行配置自定义项目名称。这应该在执行应用程序之前完成。

export LANGSMITH_PROJECT=my-project

JS 中的 SDK 兼容性

LANGSMITH_PROJECT 标志仅在 JS SDK 版本 >= 0.2.16 中受支持，如果您使用的是旧版本，请改用 LANGCHAIN_PROJECT。

动态

这在很大程度上建立在上一节的基础上，允许您为特定的 LangChainTracer 实例设置项目名称，或作为 Python 中 tracing_v2_enabled 上下文管理器的参数。

Python
TypeScript

# You can set the project name for a specific tracer instance:
from langchain.callbacks.tracers import LangChainTracer

tracer = LangChainTracer(project_name="My Project")
chain.invoke({"question": "Am I using a callback?", "context": "I'm using a callback"}, config={"callbacks": [tracer]})

# You can set the project name using the project_name parameter.
from langchain_core.tracers.context import tracing_v2_enabled
with tracing_v2_enabled(project_name="My Project"):
  chain.invoke({"question": "Am I using a context manager?", "context": "I'm using a context manager"})

// You can set the project name for a specific tracer instance:
import { LangChainTracer } from "@langchain/core/tracers/tracer_langchain";

const tracer = new LangChainTracer({ projectName: "My Project" });
await chain.invoke(
{
  question: "Am I using a callback?",
  context: "I'm using a callback"
},
{ callbacks: [tracer] }
);

为追踪添加元数据和标签

您可以通过在配置中提供元数据和标签来注解您的追踪。这对于将附加信息与追踪关联非常有用，例如执行追踪的环境或启动追踪的用户。有关如何按元数据和标签查询追踪和运行的信息，请参阅本指南

注意

当您向可运行对象附加元数据或标签时（通过 RunnableConfig 或运行时通过调用参数），它们将由该可运行对象的所有子可运行对象继承。

Python
TypeScript

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

prompt = ChatPromptTemplate.from_messages([
("system", "You are a helpful AI."),
("user", "{input}")
])
# The tag "model-tag" and metadata {"model-key": "model-value"} will be attached to the ChatOpenAI run only
chat_model = ChatOpenAI().with_config({"tags": ["model-tag"], "metadata": {"model-key": "model-value"}})
output_parser = StrOutputParser()

# Tags and metadata can be configured with RunnableConfig
chain = (prompt | chat_model | output_parser).with_config({"tags": ["config-tag"], "metadata": {"config-key": "config-value"}})

# Tags and metadata can also be passed at runtime
chain.invoke({"input": "What is the meaning of life?"}, {"tags": ["invoke-tag"], "metadata": {"invoke-key": "invoke-value"}})

import { ChatOpenAI } from "@langchain/openai";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { StringOutputParser } from "@langchain/core/output_parsers";

const prompt = ChatPromptTemplate.fromMessages([
["system", "You are a helpful AI."],
["user", "{input}"]
])
// The tag "model-tag" and metadata {"model-key": "model-value"} will be attached to the ChatOpenAI run only
const model = new ChatOpenAI().withConfig({ tags: ["model-tag"], metadata: { "model-key": "model-value" } });
const outputParser = new StringOutputParser();

// Tags and metadata can be configured with RunnableConfig
const chain = (prompt.pipe(model).pipe(outputParser)).withConfig({"tags": ["config-tag"], "metadata": {"config-key": "top-level-value"}});

// Tags and metadata can also be passed at runtime
await chain.invoke({input: "What is the meaning of life?"}, {tags: ["invoke-tag"], metadata: {"invoke-key": "invoke-value"}})

自定义运行名称

您可以通过在配置中提供名称，来自定义调用或流式传输 LangChain 代码时给定运行的名称。此名称用于在 LangSmith 中识别运行，并可用于过滤和分组运行。该名称也用作 LangSmith UI 中运行的标题。这可以通过在构造时在 RunnableConfig 对象中设置 run_name 或在 JS/TS 中在调用参数中传递 run_name 来完成。

注意

此功能目前不直接支持 LLM 对象。

Python
TypeScript

# When tracing within LangChain, run names default to the class name of the traced object (e.g., 'ChatOpenAI').
configured_chain = chain.with_config({"run_name": "MyCustomChain"})
configured_chain.invoke({"input": "What is the meaning of life?"})

# You can also configure the run name at invocation time, like below
chain.invoke({"input": "What is the meaning of life?"}, {"run_name": "MyCustomChain"})

// When tracing within LangChain, run names default to the class name of the traced object (e.g., 'ChatOpenAI').
const configuredChain = chain.withConfig({ runName: "MyCustomChain" });
await configuredChain.invoke({ input: "What is the meaning of life?" });

// You can also configure the run name at invocation time, like below
await chain.invoke({ input: "What is the meaning of life?" }, {runName: "MyCustomChain"})

自定义运行 ID

您可以通过在配置中提供 ID，来自定义调用或流式传输 LangChain 代码时给定运行的 ID。此 ID 用于在 LangSmith 中唯一标识运行，并可用于查询特定运行。该 ID 对于跨不同系统链接运行或实现自定义追踪逻辑非常有用。这可以通过在构造时在 RunnableConfig 对象中设置 run_id 或在 JS/TS 中在调用参数中传递 run_id 来完成。

注意

此功能目前不直接支持 LLM 对象。

Python
TypeScript

import uuid

my_uuid = uuid.uuid4()
# You can configure the run ID at invocation time:
chain.invoke({"input": "What is the meaning of life?"}, {"run_id": my_uuid})

import { v4 as uuidv4 } from 'uuid';

const myUuid = uuidv4();

// You can configure the run ID at invocation time, like below
await chain.invoke({ input: "What is the meaning of life?" }, { runId: myUuid });

请注意，如果您在追踪的**根**（即顶层运行）执行此操作，该运行 ID 将用作 trace_id。

访问 LangChain 调用的运行 (span) ID

当您调用 LangChain 对象时，可以访问调用的运行 ID。此运行 ID 可用于在 LangSmith 中查询运行。

在 Python 中，您可以使用 collect_runs 上下文管理器来访问运行 ID。

在 JS/TS 中，您可以使用 RunCollectorCallbackHandler 实例来访问运行 ID。

Python
TypeScript

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_core.tracers.context import collect_runs

prompt = ChatPromptTemplate.from_messages([
  ("system", "You are a helpful assistant. Please respond to the user's request only based on the given context."),
  ("user", "Question: {question}\n\nContext: {context}")
])
model = ChatOpenAI(model="gpt-4o-mini")
output_parser = StrOutputParser()

chain = prompt | model | output_parser

question = "Can you summarize this morning's meetings?"
context = "During this morning's meeting, we solved all world conflict."
with collect_runs() as cb:
result = chain.invoke({"question": question, "context": context})
# Get the root run id
run_id = cb.traced_runs[0].id
print(run_id)

import { ChatOpenAI } from "@langchain/openai";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { StringOutputParser } from "@langchain/core/output_parsers";
import { RunCollectorCallbackHandler } from "@langchain/core/tracers/run_collector";

const prompt = ChatPromptTemplate.fromMessages([
["system", "You are a helpful assistant. Please respond to the user's request only based on the given context."],
["user", "Question: {question\n\nContext: {context}"],
]);
const model = new ChatOpenAI({ modelName: "gpt-4o-mini" });
const outputParser = new StringOutputParser();

const chain = prompt.pipe(model).pipe(outputParser);
const runCollector = new RunCollectorCallbackHandler();

const question = "Can you summarize this morning's meetings?"
const context = "During this morning's meeting, we solved all world conflict."
await chain.invoke(
  { question: question, context: context },
  { callbacks: [runCollector] }
);
const runId = runCollector.tracedRuns[0].id;
console.log(runId);

确保在退出前提交所有追踪

在 LangChain Python 中，LangSmith 的追踪是在后台线程中完成的，以避免阻塞您的生产应用程序。这意味着您的进程可能在所有追踪成功发布到 LangSmith 之前结束。这在无服务器环境中尤其普遍，您的 VM 可能会在链或代理完成后立即终止。

您可以通过将 LANGCHAIN_CALLBACKS_BACKGROUND 环境变量设置为 "false" 来使回调同步。

对于两种语言，LangChain 都公开了在退出应用程序之前等待追踪提交的方法。下面是一个示例

Python
TypeScript

from langchain_openai import ChatOpenAI
from langchain_core.tracers.langchain import wait_for_all_tracers

llm = ChatOpenAI()
try:
  llm.invoke("Hello, World!")
finally:
  wait_for_all_tracers()

import { ChatOpenAI } from "@langchain/openai";
import { awaitAllCallbacks } from "@langchain/core/callbacks/promises";

try {
const llm = new ChatOpenAI();
const response = await llm.invoke("Hello, World!");
} catch (e) {
// handle error
} finally {
await awaitAllCallbacks();
}

不设置环境变量进行追踪

如其他指南所述，以下环境变量允许您配置是否启用追踪、API 端点、API 密钥和追踪项目

LANGSMITH_TRACING
LANGSMITH_API_KEY
LANGSMITH_ENDPOINT
LANGSMITH_PROJECT

然而，在某些环境中，无法设置环境变量。在这种情况下，您可以以编程方式设置追踪配置。

这在很大程度上建立在上一节的基础上。

Python
TypeScript

from langchain.callbacks.tracers import LangChainTracer
from langsmith import Client

# You can create a client instance with an api key and api url
client = Client(
  api_key="YOUR_API_KEY",  # This can be retrieved from a secrets manager
  api_url="https://api.smith.langchain.com",  # Update appropriately for self-hosted installations or the EU region
)

# You can pass the client and project_name to the LangChainTracer instance
tracer = LangChainTracer(client=client, project_name="test-no-env")
chain.invoke({"question": "Am I using a callback?", "context": "I'm using a callback"}, config={"callbacks": [tracer]})

# LangChain Python also supports a context manager which allows passing the client and project_name
from langchain_core.tracers.context import tracing_v2_enabled
with tracing_v2_enabled(client=client, project_name="test-no-env"):
  chain.invoke({"question": "Am I using a context manager?", "context": "I'm using a context manager"})

import { LangChainTracer } from "@langchain/core/tracers/tracer_langchain";
import { Client } from "langsmith";

// You can create a client instance with an api key and api url
const client = new Client(
  {
      apiKey: "YOUR_API_KEY",
      apiUrl: "https://api.smith.langchain.com", // Update appropriately for self-hosted installations or the EU region
  }
);

// You can pass the client and project_name to the LangChainTracer instance
const tracer = new LangChainTracer({client, projectName: "test-no-env"});
await chain.invoke(
{
  question: "Am I using a callback?",
  context: "I'm using a callback",
},
{ callbacks: [tracer] }
);

使用 LangChain (Python) 进行分布式追踪

LangSmith 支持使用 LangChain Python 进行分布式追踪。这允许您将不同服务和应用程序之间的运行 (spans) 链接起来。其原理与 LangSmith SDK 的分布式追踪指南类似。

import langsmith
from langchain_core.runnables import chain
from langsmith.run_helpers import get_current_run_tree

# -- This code should be in a separate file or service --
@chain
def child_chain(inputs):
    return inputs["test"] + 1

def child_wrapper(x, headers):
    with langsmith.tracing_context(parent=headers):
        child_chain.invoke({"test": x})

# -- This code should be in a separate file or service --
@chain
def parent_chain(inputs):

    rt = get_current_run_tree()
    headers = rt.to_headers()
    # ... make a request to another service with the headers
    # The headers should be passed to the other service, eventually to the child_wrapper function

parent_chain.invoke({"test": 1})

LangChain (Python) 和 LangSmith SDK 之间的互操作性

如果您的应用程序部分使用 LangChain，而其他部分使用 LangSmith SDK（请参阅本指南），您仍然可以无缝追踪整个应用程序。

LangChain 对象在 traceable 函数内被调用时将被追踪，并作为 traceable 函数的子运行绑定。

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

from langsmith import traceable

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant. Please respond to the user's request only based on the given context."),
    ("user", "Question: {question}\nContext: {context}")
])
model = ChatOpenAI(model="gpt-4o-mini")
output_parser = StrOutputParser()

chain = prompt | model | output_parser

# The above chain will be traced as a child run of the traceable function
@traceable(
    tags=["openai", "chat"],
    metadata={"foo": "bar"}
)
def invoke_runnnable(question, context):
    result = chain.invoke({"question": question, "context": context})
    return "The response is: " + result

invoke_runnnable("Can you summarize this morning's meetings?", "During this morning's meeting, we solved all world conflict.")

这将生成以下追踪树：

LangChain.JS 和 LangSmith SDK 之间的互操作性

在 `traceable` 内追踪 LangChain 对象（仅限 JS）

从 langchain@0.2.x 开始，LangChain 对象在 @traceable 函数内部使用时会自动追踪，继承可追踪函数的客户端、标签、元数据和项目名称。

对于低于 0.2.x 的 LangChain 旧版本，您需要手动传递一个由 @traceable 中的追踪上下文创建的 LangChainTracer 实例。

import { ChatOpenAI } from "@langchain/openai";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { StringOutputParser } from "@langchain/core/output_parsers";
import { getLangchainCallbacks } from "langsmith/langchain";

const prompt = ChatPromptTemplate.fromMessages([
  [
    "system",
    "You are a helpful assistant. Please respond to the user's request only based on the given context.",
  ],
  ["user", "Question: {question}\nContext: {context}"],
]);
const model = new ChatOpenAI({ modelName: "gpt-4o-mini" });
const outputParser = new StringOutputParser();

const chain = prompt.pipe(model).pipe(outputParser);

const main = traceable(
  async (input: { question: string; context: string }) => {
    const callbacks = await getLangchainCallbacks();
    const response = await chain.invoke(input, { callbacks });
    return response;
  },
  { name: "main" }
);

通过 `traceable` / RunTree API 追踪 LangChain 子运行（仅限 JS）

注意

我们正在努力改进 traceable 和 LangChain 之间的互操作性。在将 LangChain 与 traceable 结合使用时，存在以下限制：

变异从 RunnableLambda 上下文获取的 getCurrentRunTree() 将导致无操作。
不鼓励通过 getCurrentRunTree() 遍历从 RunnableLambda 获取的 RunTree，因为它可能不包含所有 RunTree 节点。
不同的子运行可能具有相同的 execution_order 和 child_execution_order 值。因此，在极端情况下，某些运行可能会根据 start_time 以不同的顺序结束。

在某些用例中，您可能希望将 traceable 函数作为 RunnableSequence 的一部分运行，或通过 RunTree API 命令式地追踪 LangChain 运行的子运行。从 LangSmith 0.1.39 和 @langchain/core 0.2.18 开始，您可以直接在 RunnableLambda 中调用 traceable 封装的函数。

import { traceable } from "langsmith/traceable";
import { RunnableLambda } from "@langchain/core/runnables";
import { RunnableConfig } from "@langchain/core/runnables";

const tracedChild = traceable((input: string) => `Child Run: ${input}`, {
  name: "Child Run",
});

const parrot = new RunnableLambda({
  func: async (input: { text: string }, config?: RunnableConfig) => {
    return await tracedChild(input.text);
  },
});

Trace Tree

或者，您可以使用 RunTree.fromRunnableConfig 将 LangChain 的 RunnableConfig 转换为等效的 RunTree 对象，或者将 RunnableConfig 作为 traceable 封装函数的第一个参数传递。

可追踪
运行树

import { traceable } from "langsmith/traceable";
import { RunnableLambda } from "@langchain/core/runnables";
import { RunnableConfig } from "@langchain/core/runnables";

const tracedChild = traceable((input: string) => `Child Run: ${input}`, {
  name: "Child Run",
});

const parrot = new RunnableLambda({
  func: async (input: { text: string }, config?: RunnableConfig) => {
    // Pass the config to existing traceable function
    await tracedChild(config, input.text);
    return input.text;
  },
});

import { RunTree } from "langsmith/run_trees";
import { RunnableLambda } from "@langchain/core/runnables";
import { RunnableConfig } from "@langchain/core/runnables";

const parrot = new RunnableLambda({
  func: async (input: { text: string }, config?: RunnableConfig) => {
    // create the RunTree from the RunnableConfig of the RunnableLambda
    const childRunTree = RunTree.fromRunnableConfig(config, {
      name: "Child Run",
    });
    
    childRunTree.inputs = { input: input.text };
    await childRunTree.postRun();
    
    childRunTree.outputs = { output: `Child Run: ${input.text}` };
    await childRunTree.patchRun();
    
    return input.text;
  },
});

如果您更喜欢视频教程，请查看 LangSmith 入门课程中的其他追踪方式视频。

使用 `LangChain` (Python 和 JS/TS) 进行追踪

安装

快速入门

1. 配置您的环境

2. 记录追踪

3. 查看您的追踪

选择性追踪

记录到特定项目

静态

动态

为追踪添加元数据和标签

自定义运行名称

自定义运行 ID

访问 LangChain 调用的运行 (span) ID

确保在退出前提交所有追踪

不设置环境变量进行追踪

使用 LangChain (Python) 进行分布式追踪

LangChain (Python) 和 LangSmith SDK 之间的互操作性

LangChain.JS 和 LangSmith SDK 之间的互操作性

在 `traceable` 内追踪 LangChain 对象（仅限 JS）

通过 `traceable` / RunTree API 追踪 LangChain 子运行（仅限 JS）

此页面是否有帮助？

您可以在 GitHub 上留下详细反馈.

安装​

快速入门​

1. 配置您的环境​

2. 记录追踪​

3. 查看您的追踪​

选择性追踪​

记录到特定项目​

静态​

动态​

为追踪添加元数据和标签​

自定义运行名称​

自定义运行 ID​

访问 LangChain 调用的运行 (span) ID​

确保在退出前提交所有追踪​

不设置环境变量进行追踪​

使用 LangChain (Python) 进行分布式追踪​

LangChain (Python) 和 LangSmith SDK 之间的互操作性​

LangChain.JS 和 LangSmith SDK 之间的互操作性​

在 traceable 内追踪 LangChain 对象（仅限 JS）​

通过 traceable / RunTree API 追踪 LangChain 子运行（仅限 JS）​

此页面是否有帮助？

您可以在 GitHub 上 留下详细反馈.

安装

快速入门

1. 配置您的环境

2. 记录追踪

3. 查看您的追踪

选择性追踪

记录到特定项目

静态

动态

为追踪添加元数据和标签

自定义运行名称

自定义运行 ID

访问 LangChain 调用的运行 (span) ID

确保在退出前提交所有追踪

不设置环境变量进行追踪

使用 LangChain (Python) 进行分布式追踪

LangChain (Python) 和 LangSmith SDK 之间的互操作性

LangChain.JS 和 LangSmith SDK 之间的互操作性

在 `traceable` 内追踪 LangChain 对象（仅限 JS）

通过 `traceable` / RunTree API 追踪 LangChain 子运行（仅限 JS）

您可以在 GitHub 上留下详细反馈.