LangGraph 命令行界面

LangGraph 命令行界面包含用于在 Docker 中本地构建和运行 LangGraph 云 API 服务器的命令。对于开发和测试，你可以使用该命令行界面部署本地 API 服务器。

安装

1. 确保已安装 Docker（例如，运行 docker --version 命令）。

2. 安装 CLI 包：

   PythonJS

   pip install langgraph-cli
   
   # 通过 Homebrew 安装
   brew install langgraph-cli
   

   npx @langchain/langgraph-cli
   
   # 全局安装，可通过 `langgraphjs` 命令使用
   npm install -g @langchain/langgraph-cli
   

3. 运行 langgraph --help 或 npx @langchain/langgraph-cli --help 命令，以确认 CLI 能正常工作。

配置文件

LangGraph CLI 需要一个遵循此 架构 的 JSON 配置文件。它包含以下属性：

注意

LangGraph CLI 默认使用当前目录中的配置文件 langgraph.json。

PythonJS

键	描述
dependencies	必需。LangGraph 云 API 服务器的依赖项数组。依赖项可以是以下之一： 单个句点 (".")，这将查找本地 Python 包。 包含 pyproject.toml、setup.py 或 requirements.txt 的目录路径。 例如，如果 requirements.txt 位于项目目录的根目录中，请指定 "./"。如果它位于名为 local_package 的子目录中，请指定 "./local_package"。不要直接指定字符串 "requirements.txt"。 Python 包名称。
graphs	必需。从图 ID 到定义已编译图或创建图的函数的路径的映射。示例： ./your_package/your_file.py:variable，其中 variable 是 langgraph.graph.state.CompiledStateGraph 的实例 ./your_package/your_file.py:make_graph，其中 make_graph 是一个接受配置字典 (langchain_core.runnables.RunnableConfig) 并创建 langgraph.graph.state.StateGraph / langgraph.graph.state.CompiledStateGraph 实例的函数。
auth	(v0.0.11 版本新增) 包含身份验证处理程序路径的身份验证配置。示例：./your_package/auth.py:auth，其中 auth 是 langgraph_sdk.Auth 的实例。有关详细信息，请参阅 身份验证指南。
env	.env 文件的路径或环境变量与其值的映射。
store	用于向 BaseStore 添加语义搜索和/或生存时间 (TTL) 的配置。包含以下字段： index（可选）：用于语义搜索索引的配置，包含字段 embed、dims 和可选的 fields。 ttl（可选）：用于项目过期的配置。一个包含可选字段的对象：refresh_on_read（布尔值，默认为 true）、default_ttl（浮点数，以 分钟 为单位的寿命，默认为不过期）和 sweep_interval_minutes（整数，检查过期项目的频率，默认为不进行清理）。
python_version	3.11、3.12 或 3.13。默认为 3.11。
node_version	指定 node_version: 20 以使用 LangGraph.js。
pip_config_file	pip 配置文件的路径。
dockerfile_lines	从父镜像导入后要添加到 Dockerfile 的额外行数组。
checkpointer	检查点管理器的配置。包含一个 ttl 字段，该字段是一个具有以下键的对象： strategy：如何处理过期的检查点（例如，"delete"）。 sweep_interval_minutes：系统检查过期检查点的频率（整数）。 default_ttl：检查点的默认生存时间，以 分钟 为单位（整数）。定义在应用指定策略之前检查点的保留时间。
http	HTTP 服务器配置，包含以下字段： app：自定义 Starlette/FastAPI 应用的路径（例如，"./src/agent/webapp.py:app"）。请参阅 自定义路由指南。 disable_assistants：禁用 /assistants 路由 disable_threads：禁用 /threads 路由 disable_runs：禁用 /runs 路由 disable_store：禁用 /store 路由 disable_meta：禁用 /ok、/info、/metrics 和 /docs 路由 cors：CORS 配置，包含 allow_origins、allow_methods、allow_headers 等字段。

键	描述
graphs	必需。从图 ID 到定义已编译图或创建图的函数的路径的映射。示例： ./src/graph.ts:variable，其中 variable 是 CompiledStateGraph 的实例 ./src/graph.ts:makeGraph，其中 makeGraph 是一个接受配置字典 (LangGraphRunnableConfig) 并创建 StateGraph / CompiledStateGraph 实例的函数。
env	.env 文件的路径或环境变量与其值的映射。
store	用于向 BaseStore 添加语义搜索和/或生存时间 (TTL) 的配置。包含以下字段： index（可选）：用于语义搜索索引的配置，包含字段 embed、dims 和可选的 fields。 ttl（可选）：用于项目过期的配置。一个包含可选字段的对象：refresh_on_read（布尔值，默认为 true）、default_ttl（浮点数，以 分钟 为单位的寿命，默认为不过期）和 sweep_interval_minutes（整数，检查过期项目的频率，默认为不进行清理）。
node_version	指定 node_version: 20 以使用 LangGraph.js。
dockerfile_lines	从父镜像导入后要添加到 Dockerfile 的额外行数组。
checkpointer	检查点管理器的配置。包含一个 ttl 字段，该字段是一个具有以下键的对象： strategy：如何处理过期的检查点（例如，"delete"）。 sweep_interval_minutes：系统检查过期检查点的频率（整数）。 default_ttl：检查点的默认生存时间，以 分钟 为单位（整数）。定义在应用指定策略之前检查点的保留时间。

示例

PythonJS

基本配置

{
  "dependencies": ["."],
  "graphs": {
    "chat": "./chat/graph.py:graph"
  }
}

为存储添加语义搜索

所有部署都附带一个基于数据库的 BaseStore。在你的 langgraph.json 中添加 "index" 配置将在你的部署的 BaseStore 中启用 语义搜索。

index.fields 配置决定了要嵌入文档的哪些部分：

• 如果省略或设置为 ["$"]，则将嵌入整个文档
• 要嵌入特定字段，请使用 JSON 路径表示法：["metadata.title", "content.text"]
• 缺少指定字段的文档仍将被存储，但这些字段不会有嵌入向量
• 你仍然可以在 put 操作时使用 index 参数覆盖特定项目要嵌入的字段

{
  "dependencies": ["."],
  "graphs": {
    "memory_agent": "./agent/graph.py:graph"
  },
  "store": {
    "index": {
      "embed": "openai:text-embedding-3-small",
      "dims": 1536,
      "fields": ["$"]
    }
  }
}

常见模型维度

• openai:text-embedding-3-large：3072
• openai:text-embedding-3-small：1536
• openai:text-embedding-ada-002：1536
• cohere:embed-english-v3.0：1024
• cohere:embed-english-light-v3.0：384
• cohere:embed-multilingual-v3.0：1024
• cohere:embed-multilingual-light-v3.0：384

使用自定义嵌入函数进行语义搜索

如果你想使用自定义嵌入函数进行语义搜索，可以传递自定义嵌入函数的路径：

{
  "dependencies": ["."],
  "graphs": {
    "memory_agent": "./agent/graph.py:graph"
  },
  "store": {
    "index": {
      "embed": "./embeddings.py:embed_texts",
      "dims": 768,
      "fields": ["text", "summary"]
    }
  }
}

存储配置中的 embed 字段可以引用一个自定义函数，该函数接受一个字符串列表并返回一个嵌入向量列表。示例实现：

# embeddings.py
def embed_texts(texts: list[str]) -> list[list[float]]:
    """用于语义搜索的自定义嵌入函数。"""
    # 使用你首选的嵌入模型实现
    return [[0.1, 0.2, ...] for _ in texts]  # 维度为 dims 的向量

添加自定义身份验证

{
  "dependencies": ["."],
  "graphs": {
    "chat": "./chat/graph.py:graph"
  },
  "auth": {
    "path": "./auth.py:auth",
    "openapi": {
      "securitySchemes": {
        "apiKeyAuth": {
          "type": "apiKey",
          "in": "header",
          "name": "X-API-Key"
        }
      },
      "security": [{ "apiKeyAuth": [] }]
    },
    "disable_studio_auth": false
  }
}

有关详细信息，请参阅 身份验证概念指南，并参阅 设置自定义身份验证 指南以获取该过程的实际操作步骤。

配置存储项的生存时间 (TTL)

你可以使用 store.ttl 键为 BaseStore 中的项目/内存配置默认数据过期时间。这决定了项目在最后一次访问后保留的时间（根据 refresh_on_read，读取操作可能会刷新计时器）。请注意，这些默认值可以通过修改 get、search 等操作中的相应参数在每次调用时进行覆盖。

ttl 配置是一个包含可选字段的对象：

• refresh_on_read：如果为 true（默认值），通过 get 或 search 访问项目会重置其过期计时器。设置为 false 则仅在写入 (put) 时刷新 TTL。
• default_ttl：项目的默认寿命，以 分钟 为单位。如果未设置，项目默认不会过期。
• sweep_interval_minutes：系统应每隔多长时间（以分钟为单位）运行一个后台进程来删除过期项目。如果未设置，则不会自动进行清理。

以下是一个启用 7 天 TTL（10080 分钟）、在读取时刷新并每小时进行一次清理的示例：

{
  "dependencies": ["."],
  "graphs": {
    "memory_agent": "./agent/graph.py:graph"
  },
  "store": {
    "ttl": {
      "refresh_on_read": true,
      "sweep_interval_minutes": 60,
      "default_ttl": 10080 
    }
  }
}

配置检查点的生存时间 (TTL)

你可以使用 checkpointer 键配置检查点的生存时间 (TTL)。这决定了检查点数据在根据指定策略（例如，删除）自动处理之前保留的时间。ttl 配置是一个包含以下内容的对象：

• strategy：对过期检查点采取的操作（目前仅接受 "delete" 选项）。
• sweep_interval_minutes：系统检查过期检查点的频率（以分钟为单位）。
• default_ttl：检查点的默认寿命，以 分钟 为单位。

以下是一个设置默认 TTL 为 30 天（43200 分钟）的示例：

{
  "dependencies": ["."],
  "graphs": {
    "chat": "./chat/graph.py:graph"
  },
  "checkpointer": {
    "ttl": {
      "strategy": "delete",
      "sweep_interval_minutes": 10,
      "default_ttl": 43200
    }
  }
}

在这个示例中，超过 30 天的检查点将被删除，并且每 10 分钟进行一次检查。

基本配置

{
  "graphs": {
    "chat": "./src/graph.ts:graph"
  }
}

命令

使用方法

PythonJS

LangGraph CLI 的基础命令是 langgraph。

langgraph [选项] 命令 [参数]

LangGraph.js CLI 的基础命令是 langgraphjs。

npx @langchain/langgraph-cli [选项] 命令 [参数]

我们建议使用 npx 以始终使用 CLI 的最新版本。

dev

PythonJS

以开发模式运行 LangGraph API 服务器，具备热重载和调试功能。这个轻量级服务器无需安装 Docker，适用于开发和测试。状态会持久化到本地目录。

注意

目前，CLI 仅支持 Python >= 3.11。

安装

此命令需要安装 "inmem" 额外依赖：

pip install -U "langgraph-cli[inmem]"

使用方法

langgraph dev [选项]

选项

选项	默认值	描述
-c, --config 文件	langgraph.json	声明依赖项、图和环境变量的配置文件路径
--host 文本	127.0.0.1	服务器绑定的主机
--port 整数	2024	服务器绑定的端口
--no-reload		禁用自动重载
--n-jobs-per-worker 整数		每个工作进程的作业数。默认值为 10
--debug-port 整数		调试器监听的端口
--help		显示命令文档

以开发模式运行 LangGraph API 服务器，具备热重载功能。这个轻量级服务器无需安装 Docker，适用于开发和测试。状态会持久化到本地目录。

使用方法

npx @langchain/langgraph-cli dev [选项]

选项

选项	默认值	描述
-c, --config 文件	langgraph.json	声明依赖项、图和环境变量的配置文件路径
--host 文本	127.0.0.1	服务器绑定的主机
--port 整数	2024	服务器绑定的端口
--no-reload		禁用自动重载
--n-jobs-per-worker 整数		每个工作进程的作业数。默认值为 10
--debug-port 整数		调试器监听的端口
--help		显示命令文档

build

PythonJS

构建 LangGraph Cloud API 服务器的 Docker 镜像。

使用方法

langgraph build [选项]

选项

选项	默认值	描述
--platform 文本		构建 Docker 镜像的目标平台。示例：langgraph build --platform linux/amd64,linux/arm64
-t, --tag 文本		必需。Docker 镜像的标签。示例：langgraph build -t my-image
--pull / --no-pull	--pull	使用最新的远程 Docker 镜像进行构建。使用 --no-pull 以使用本地构建的镜像运行 LangGraph Cloud API 服务器。
-c, --config 文件	langgraph.json	声明依赖项、图和环境变量的配置文件路径。
--help		显示命令文档。

构建 LangGraph Cloud API 服务器的 Docker 镜像。

使用方法

npx @langchain/langgraph-cli build [选项]

选项

选项	默认值	描述
--platform 文本		构建 Docker 镜像的目标平台。示例：langgraph build --platform linux/amd64,linux/arm64
-t, --tag 文本		必需。Docker 镜像的标签。示例：langgraph build -t my-image
--no-pull		使用本地构建的镜像。默认值为 false，即使用最新的远程 Docker 镜像进行构建。
-c, --config 文件	langgraph.json	声明依赖项、图和环境变量的配置文件路径。
--help		显示命令文档。

up

PythonJS

启动 LangGraph API 服务器。进行本地测试时，需要一个有权限访问 LangGraph Cloud 封闭测试版的 LangSmith API 密钥。生产环境使用需要许可证密钥。

使用方法

langgraph up [选项]

选项

选项	默认值	描述
--wait		在返回之前等待服务启动。隐含 --detach
--postgres-uri 文本	本地数据库	用于数据库的 Postgres URI。
--watch		文件更改时重启
--debugger-base-url 文本	http://127.0.0.1:[端口]	调试器用于访问 LangGraph API 的 URL。
--debugger-port 整数		本地拉取调试器镜像并在指定端口提供 UI 服务
--verbose		显示服务器日志的更多输出。
-c, --config 文件	langgraph.json	声明依赖项、图和环境变量的配置文件路径。
-d, --docker-compose 文件		包含要启动的其他服务的 docker-compose.yml 文件路径。
-p, --port 整数	8123	暴露的端口。示例：langgraph up --port 8000
--pull / --no-pull	pull	拉取最新镜像。使用 --no-pull 以使用本地构建的镜像运行服务器。示例：langgraph up --no-pull
--recreate / --no-recreate	no-recreate	即使容器的配置和镜像未更改也重新创建容器
--help		显示命令文档。

启动 LangGraph API 服务器。进行本地测试时，需要一个有权限访问 LangGraph Cloud 封闭测试版的 LangSmith API 密钥。生产环境使用需要许可证密钥。

使用方法

npx @langchain/langgraph-cli up [选项]

选项

选项	默认值	描述
--wait		在返回之前等待服务启动。隐含 --detach
--postgres-uri 文本	本地数据库	用于数据库的 Postgres URI。
--watch		文件更改时重启
-c, --config 文件	langgraph.json	声明依赖项、图和环境变量的配置文件路径。
-d, --docker-compose 文件		包含要启动的其他服务的 docker-compose.yml 文件路径。
-p, --port 整数	8123	暴露的端口。示例：langgraph up --port 8000
--no-pull		使用本地构建的镜像。默认值为 false，即使用最新的远程 Docker 镜像进行构建。
--recreate		即使容器的配置和镜像未更改也重新创建容器
--help		显示命令文档。

dockerfile

PythonJS

生成用于构建 LangGraph Cloud API 服务器 Docker 镜像的 Dockerfile。

使用方法

langgraph dockerfile [选项] 保存路径

选项

选项	默认值	描述
-c, --config 文件	langgraph.json	配置文件的路径，该文件声明了依赖项、图和环境变量。
--help		显示此消息并退出。

示例：

langgraph dockerfile -c langgraph.json Dockerfile

这将生成一个类似于以下内容的 Dockerfile：

FROM langchain/langgraph-api:3.11

ADD ./pipconf.txt /pipconfig.txt

RUN PIP_CONFIG_FILE=/pipconfig.txt PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt langchain_community langchain_anthropic langchain_openai wikipedia scikit-learn

ADD ./graphs /deps/__outer_graphs/src
RUN set -ex && \
    for line in '[project]' \
                'name = "graphs"' \
                'version = "0.1"' \
                '[tool.setuptools.package-data]' \
                '"*" = ["**/*"]'; do \
        echo "$line" >> /deps/__outer_graphs/pyproject.toml; \
    done

RUN PIP_CONFIG_FILE=/pipconfig.txt PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt -e /deps/*

ENV LANGSERVE_GRAPHS='{"agent": "/deps/__outer_graphs/src/agent.py:graph", "storm": "/deps/__outer_graphs/src/storm.py:graph"}'

更新你的 langgraph.json 文件

langgraph dockerfile 命令会将 langgraph.json 文件中的所有配置转换为 Dockerfile 命令。使用此命令时，每当更新 langgraph.json 文件，都必须重新运行该命令。否则，在构建或运行 Dockerfile 时，更改将不会生效。

生成用于构建 LangGraph Cloud API 服务器 Docker 镜像的 Dockerfile。

使用方法

npx @langchain/langgraph-cli dockerfile [选项] 保存路径

选项

选项	默认值	描述
-c, --config 文件	langgraph.json	配置文件的路径，该文件声明了依赖项、图和环境变量。
--help		显示此消息并退出。

示例：

npx @langchain/langgraph-cli dockerfile -c langgraph.json Dockerfile

这将生成一个类似于以下内容的 Dockerfile：

FROM langchain/langgraphjs-api:20

ADD . /deps/agent

RUN cd /deps/agent && yarn install

ENV LANGSERVE_GRAPHS='{"agent":"./src/react_agent/graph.ts:graph"}'

WORKDIR /deps/agent

RUN (test ! -f /api/langgraph_api/js/build.mts && echo "Prebuild script not found, skipping") || tsx /api/langgraph_api/js/build.mts

更新你的 langgraph.json 文件

npx @langchain/langgraph-cli dockerfile 命令会将 langgraph.json 文件中的所有配置转换为 Dockerfile 命令。使用此命令时，每当更新 langgraph.json 文件，都必须重新运行该命令。否则，在构建或运行 Dockerfile 时，更改将不会生效。

Comments