使用 `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] }
);

向追踪添加元数据和标签

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

注意

当您将元数据或标签附加到可运行对象时（通过 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 代码时，通过在 Config 中提供运行名称来自定义给定运行的名称。此名称用于在 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

您可以在调用或流式传输 LangChain 代码时，通过在 Config 中提供运行 ID 来自定义给定运行的 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",
  }
);

// 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 进行分布式追踪。这允许您链接跨不同服务和应用程序的运行（span）。其原理与 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（请参阅本指南），您仍然可以无缝地追踪整个应用程序。

当在 traceable 函数中调用 LangChain 对象时，将对其进行追踪，并将其绑定为 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() 获取的 RunTree 将导致无操作。
不建议遍历从 RunnableLambda 通过 getCurrentRunTree() 获取的 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 包装函数的第一个参数传递。

Traceable
Run Tree

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 上.