Runnable 接口

¥Runnable interface

Runnable 接口是使用 LangChain 组件的基础，它已在许多 LangChain 组件中实现，例如 语言模型、输出解析器、retrievers、编译的 LangGraph 图表 等。

¥The Runnable interface is foundational for working with LangChain components, and it's implemented across many of them, such as language models, output parsers, retrievers, compiled LangGraph graphs and more.

本指南介绍 Runnable 接口的主要概念和方法，该接口允许开发者以一致且可预测的方式与各种 LangChain 组件进行交互。

¥This guide covers the main concepts and methods of the Runnable interface, which allows developers to interact with various LangChain components in a consistent and predictable manner.

Related Resources

• "Runnable" 接口 API 参考 提供了 Runnable 接口及其方法的详细概述。

  ¥The "Runnable" Interface API Reference provides a detailed overview of the Runnable interface and its methods.

• 内置 Runnables 列表可在 LangChain 核心 API 参考 中找到。在使用 LangChain 表达式语言 (LCEL) 在 LangChain 中编写自定义 "chains" 时，许多 Runnable 都非常有用。

  ¥A list of built-in Runnables can be found in the LangChain Core API Reference. Many of these Runnables are useful when composing custom "chains" in LangChain using the LangChain Expression Language (LCEL).

可运行接口概述

¥Overview of runnable interface

Runnable 方式定义了一个标准接口，允许 Runnable 组件执行以下操作：

¥The Runnable way defines a standard interface that allows a Runnable component to be:

• 调用方式：单个输入转换为输出。

  ¥Invoked: A single input is transformed into an output.

• 批量处理：多个输入可以高效地转换为输出。

  ¥Batched: Multiple inputs are efficiently transformed into outputs.

• 流式传输：输出在生成时即进行流式传输。

  ¥Streamed: Outputs are streamed as they are produced.

• 已检查：可以访问 Runnable 的输入、输出和配置的示意图信息。

  ¥Inspected: Schematic information about Runnable's input, output, and configuration can be accessed.

• 组成：可以使用 LangChain 表达式语言 (LCEL) 组合多个 Runnable 来协同工作，从而创建复杂的管道。

  ¥Composed: Multiple Runnables can be composed to work together using the LangChain Expression Language (LCEL) to create complex pipelines.

请查看 LCEL 备忘单 获取涉及 Runnable 接口和 LCEL 表达式的一些常见模式。

¥Please review the LCEL Cheatsheet for some common patterns that involve the Runnable interface and LCEL expressions.

优化并行执行（批处理）

¥Optimized parallel execution (batch)

LangChain Runnables 提供内置的 batch API，允许你并行处理多个输入。

¥LangChain Runnables offer a built-in batch API that allow you to process multiple inputs in parallel.

使用此方法可以在需要处理多个独立输入时显著提高性能，因为处理可以并行进行，而不是顺序进行。

¥Using this method can significantly improve performance when needing to process multiple independent inputs, as the processing can be done in parallel instead of sequentially.

批处理方法如下：

¥The batching method is:

• batch：并行处理多个输入，并按与输入相同的顺序返回结果。

  ¥batch: Process multiple inputs in parallel, returning results in the same order as the inputs.

batch 的默认实现并行执行 invoke 方法。

¥The default implementation of batch executed the invoke method in parallel.

某些 Runnable 可能会提供针对其特定用例优化的 batch 实现（例如，依赖模型提供商提供的 batch API）。

¥Some Runnables may provide their own implementations of batch that are optimized for their specific use case (e.g., rely on a batch API provided by a model provider).

tip

当使用 batch 处理大量输入时，用户可能希望控制最大并行调用数。这可以通过在 RunnableConfig 对象中设置 maxConcurrency 属性来实现。有关更多信息，请参阅 RunnableConfig。

¥When processing a large number of inputs using batch, users may want to control the maximum number of parallel calls. This can be done by setting the maxConcurrency attribute in the RunnableConfig object. See the RunnableConfig for more information.

流式传输 API

¥Streaming apis

流式传输对于使基于 LLM 的应用对终端用户响应至关重要。

¥Streaming is critical in making applications based on LLMs feel responsive to end-users.

Runnable 公开以下三个流式 API：

¥Runnables expose the following three streaming APIs:

1. stream：在生成时输出一个 Runnable。

   ¥stream: yields the output a Runnable as it is generated.

2. streamEvents：一个更高级的流式 API，用于流式传输中间步骤和最终输出

   ¥streamEvents: a more advanced streaming API that allows streaming intermediate steps and final output

3. 旧版 streamLog：一个传统的流式 API，用于流式传输中间步骤和最终输出

   ¥legacy streamLog: a legacy streaming API that streams intermediate steps and final output

有关如何在 LangChain 中进行流式传输的更多详细信息，请参阅 流式传输概念指南。

¥Please refer to the Streaming Conceptual Guide for more details on how to stream in LangChain.

输入和输出类型

¥Input and output types

每个 Runnable 都具有输入和输出类型。这些输入和输出类型可以是任何 TypeScript 对象，并由 Runnable 本身定义。

¥Every Runnable is characterized by an input and output type. These input and output types can be any TypeScript object, and are defined by the Runnable itself.

导致 Runnable 执行的 Runnable 方法（例如 invoke、batch、stream、streamEvents）可与以下输入和输出类型配合使用。

¥Runnable methods that result in the execution of the Runnable (e.g., invoke, batch, stream, streamEvents) work with these input and output types.

• invoke：接受输入并返回输出。

  ¥invoke: Accepts an input and returns an output.

• batch：接受输入列表并返回输出列表。

  ¥batch: Accepts a list of inputs and returns a list of outputs.

• stream：接受输入并返回生成输出的生成器。

  ¥stream: Accepts an input and returns a generator that yields outputs.

输入类型和输出类型因组件而异：

¥The input type and output type vary by component:

Component	Input Type	Output Type
Prompt	object	PromptValue
ChatModel	a string, list of chat messages or a PromptValue	ChatMessage
LLM	a string, list of chat messages or a PromptValue	string
OutputParser	the output of an LLM or ChatModel	Depends on the parser
Retriever	a string	List of Documents
Tool	a string or object, depending on the tool	Depends on the tool

有关输入和输出类型及其使用方法的更多信息，请参阅各个组件的文档。

¥Please refer to the individual component documentation for more information on the input and output types and how to use them.

RunnableConfig

任何用于执行可运行对象（例如 invoke、batch、stream、streamEvents）的方法都接受名为 RunnableConfig（API 参考）的第二个参数。此参数是一个对象，包含 Runnable 的配置，将在 Runnable 执行期间使用。

¥Any of the methods that are used to execute the runnable (e.g., invoke, batch, stream, streamEvents) accept a second argument called RunnableConfig (API Reference). This argument is an object that contains configuration for the Runnable that will be used at run time during the execution of the runnable.

RunnableConfig 可以定义以下任何属性：

¥A RunnableConfig can have any of the following properties defined:

Attribute	Description
runName	Name used for the given Runnable (not inherited).
runId	Unique identifier for this call. sub-calls will get their own unique run ids.
tags	Tags for this call and any sub-calls.
metadata	Metadata for this call and any sub-calls.
callbacks	Callbacks for this call and any sub-calls.
maxConcurrency	Maximum number of parallel calls to make (e.g., used by batch).
recursionLimit	Maximum number of times a call can recurse (e.g., used by Runnables that return Runnables)
configurable	Runtime values for configurable attributes of the Runnable.

将 config 传递给 invoke 方法的操作如下：

¥Passing config to the invoke method is done like so:

await someRunnable.invoke(someInput, {
  runName: "myRun",
  tags: ["tag1", "tag2"],
  metadata: { key: "value" },
});

RunnableConfig 传播

¥Propagation of RunnableConfig

许多 Runnables 由其他 Runnable 组成，因此将 RunnableConfig 传播到 Runnable 发出的所有子调用非常重要。这允许向父 Runnable 提供运行时配置值，所有子调用都会继承这些值。

¥Many Runnables are composed of other Runnables, and it is important that the RunnableConfig is propagated to all sub-calls made by the Runnable. This allows providing run time configuration values to the parent Runnable that are inherited by all sub-calls.

如果不是这种情况，则无法设置和传播 callbacks 或其他配置值（例如 tags 和 metadata，这些值预计会被所有子调用继承）。

¥If this were not the case, it would be impossible to set and propagate callbacks or other configuration values like tags and metadata which are expected to be inherited by all sub-calls.

创建新的 Runnables 主要有两种模式：

¥There are two main patterns by which new Runnables are created:

1. 声明式使用 LangChain 表达式语言 (LCEL)：

   ¥Declaratively using LangChain Expression Language (LCEL):

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

2. 使用 自定义 Runnable（例如 RunnableLambda）或使用 tool 函数：

   ¥Using a custom Runnable (e.g., RunnableLambda) or using the tool function:

   const foo = (input) => {
     // Note that .invoke() is used directly here
     return barRunnable.invoke(input);
   };
   const fooRunnable = RunnableLambda.from(foo);

LangChain 将尝试为这两种模式自动传播 RunnableConfig。

¥LangChain will try to propagate RunnableConfig automatically for both of the patterns.

手动传播 RunnableConfig 的操作如下：

¥Propagating the RunnableConfig manually is done like so:

// Note the config argument
const foo = (input, config) => {
  return barRunnable.invoke(input, config);
};
const fooRunnable = RunnableLambda.from(foo);

设置自定义运行名称、标签和元数据

¥Setting custom run name, tags, and metadata

RunnableConfig 对象的 runName、tags 和 metadata 属性可用于为给定 Runnable 的运行名称、标签和元数据设置自定义值。

¥The runName, tags, and metadata attributes of the RunnableConfig object can be used to set custom values for the run name, tags, and metadata for a given Runnable.

runName 是一个字符串，可用于设置运行的自定义名称。此名称将在日志和其他地方用于标识运行。它不会被子调用继承。

¥The runName is a string that can be used to set a custom name for the run. This name will be used in logs and other places to identify the run. It is not inherited by sub-calls.

tags 和 metadata 属性分别是数组和对象，可用于为运行设置自定义标签和元数据。这些值由子调用继承。

¥The tags and metadata attributes are arrays and objects, respectively, that can be used to set custom tags and metadata for the run. These values are inherited by sub-calls.

使用这些属性对于跟踪和调试运行非常有用，因为它们将作为跟踪属性显示在 LangSmith 中，你可以根据这些属性进行过滤和搜索。

¥Using these attributes can be useful for tracking and debugging runs, as they will be surfaced in LangSmith as trace attributes that you can filter and search on.

这些属性也将传播到 callbacks，并将作为流中每个事件的一部分出现在流 API（如 streamEvents）中。

¥The attributes will also be propagated to callbacks, and will appear in streaming APIs like streamEvents as part of each event in the stream.

Related

• 如何使用 LangChain

  ¥How-to trace with LangChain

设置运行 ID

¥Setting run id

note

这是一项高级功能，大多数用户都不需要。

¥This is an advanced feature that is unnecessary for most users.

你可能需要为给定的运行设置自定义 runId，以便以后引用它或将其与其他系统关联。

¥You may need to set a custom runId for a given run, in case you want to reference it later or correlate it with other systems.

runId 必须是有效的 UUID 字符串，并且每次运行都必须唯一。它用于标识父运行，子类将自动获得自己唯一的运行 ID。

¥The runId MUST be a valid UUID string and unique for each run. It is used to identify the parent run, sub-class will get their own unique run ids automatically.

要设置自定义 runId，你可以在调用 Runnable 时将其作为键值对传递到 config 对象中：

¥To set a custom runId, you can pass it as a key-value pair in the config object when invoking the Runnable:

import { v4 as uuidv4 } from "uuid";

const runId = uuidv4();

await someRunnable.invoke(someInput, {
  runId,
});

// Do something with the runId

设置递归限制

¥Setting recursion limit

note

这是一项高级功能，大多数用户都不需要。

¥This is an advanced feature that is unnecessary for most users.

某些 Runnable 可能会返回其他 Runnable，如果处理不当，可能会导致无限递归。为了防止这种情况，你可以在 RunnableConfig 对象中设置一个 recursion_limit。这将限制 Runnable 的递归次数。

¥Some Runnables may return other Runnables, which can lead to infinite recursion if not handled properly. To prevent this, you can set a recursion_limit in the RunnableConfig object. This will limit the number of times a Runnable can recurse.

设置最大并发数

¥Setting max concurrency

如果使用 batch 方法，你可以设置 RunnableConfig 对象中的 maxConcurrency 属性来控制最大并行调用数。当你想限制并行调用数量以防止服务器或 API 过载时，这非常有用。

¥If using the batch methods, you can set the maxConcurrency attribute in the RunnableConfig object to control the maximum number of parallel calls to make. This can be useful when you want to limit the number of parallel calls to prevent overloading a server or API.

设置可配置

¥Setting configurable

configurable 字段用于传递 Runnable 可配置属性的运行时值。

¥The configurable field is used to pass runtime values for configurable attributes of the Runnable.

它在 LangGraph、LangGraph 持久化 和 memory 中经常使用。

¥It is used frequently in LangGraph with LangGraph Persistence and memory.

它在 RunnableWithMessageHistory 中用于类似目的，指定一个 session_id 来跟踪对话历史记录。

¥It is used for a similar purpose in RunnableWithMessageHistory to specify a session_id to keep track of conversation history.

设置回调

¥Setting callbacks

使用此选项可在运行时为可运行对象配置 callbacks。回调函数将传递给可运行函数发出的所有子调用。

¥Use this option to configure callbacks for the runnable at runtime. The callbacks will be passed to all sub-calls made by the runnable.

await someRunnable.invoke(someInput, {
  callbacks: [SomeCallbackHandler(), AnotherCallbackHandler()],
});

请阅读 回调概念指南 指南以获取有关如何在 LangChain 中使用回调的更多信息。

¥Please read the Callbacks Conceptual Guide for more information on how to use callbacks in LangChain.

从函数创建可运行对象

¥Creating a runnable from a function

你可能需要创建一个自定义的 Runnable 来运行任意逻辑。如果你使用 LangChain 表达式语言 (LCEL) 组合多个 Runnable 并且需要在其中一个步骤中添加自定义处理逻辑，则此功能尤其有用。

¥You may need to create a custom Runnable that runs arbitrary logic. This is especially useful if using LangChain Expression Language (LCEL) to compose multiple Runnables and you need to add custom processing logic in one of the steps.

从函数创建自定义 Runnable 有两种方法：

¥There are two ways to create a custom Runnable from a function:

• RunnableLambda：在不需要流式传输的情况下使用此 API 进行简单的转换。

  ¥RunnableLambda: Use this simple transformations where streaming is not required.

• RunnableGenerator：当需要流式传输时，可使用此方法进行更复杂的转换。

  ¥RunnableGenerator: use this for more complex transformations when streaming is needed.

有关如何使用 RunnableLambda 和 RunnableGenerator 的更多信息，请参阅 如何运行自定义函数 指南。

¥See the How to run custom functions guide for more information on how to use RunnableLambda and RunnableGenerator.

info

用户不应尝试继承 Runnable 类来创建新的自定义 Runnable。它比简单地使用 RunnableLambda 或 RunnableGenerator 复杂得多，也更容易出错。

¥Users should not try to subclass Runnables to create a new custom Runnable. It is much more complex and error-prone than simply using RunnableLambda or RunnableGenerator.