【LangGraph】CLI（命令行界面）：供了用于在本地 Docker 中构建和运行 LangGraph 平台 API 服务器的命令
LangGraph 命令行界面（CLI）
LangGraph 命令行界面（CLI）提供了用于在本地 Docker 中构建和运行 LangGraph 平台 API 服务器的命令。对于开发和测试，您可以使用 CLI 部署本地 API 服务器。
1. 安装
- 确保已安装 Docker（例如，运行
docker --version检查）。 - 安装 CLI 包：
Python：
JavaScript：pip install langgraph-clinpx @langchain/langgraph-cli # 全局安装，将可用作 'langgraphjs' npm install -g @langchain/langgraph-cli - 运行命令
langgraph --help或npx @langchain/langgraph-cli --help以确认 CLI 正常工作。
2. 配置文件
LangGraph CLI 要求使用 JSON 配置文件，遵循以下模式。配置文件默认位于当前目录的 langgraph.json 文件中。
2.1 Python 配置
| 键 | 描述 |
|---|---|
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 的实例。参见认证指南。 | |
base_image | 可选。LangGraph API 服务器的基础镜像。默认使用 langchain/langgraph-api。可用于固定特定版本的 LangGraph API，例如 langchain/langgraph-server:0.2。参见 Docker Hub。（langgraph-cli>=0.2.8 起支持） |
env | .env 文件路径或环境变量到其值的映射。 |
store | BaseStore 的语义搜索和/或生存时间（TTL）配置，包含以下字段： |
- index（可选）：语义搜索索引配置，包含 embed（嵌入模型）、dims（嵌入维度）和可选的 fields（要嵌入的字段）。 | |
- ttl（可选）：项目过期配置，包含可选字段： | |
- refresh_on_read（布尔值，默认 true）：读取时是否刷新 TTL。 | |
- default_ttl（浮点数，分钟为单位，默认无过期）：项目默认寿命。 | |
- sweep_interval_minutes（整数，默认无清理）：检查过期项目的频率。 | |
ui | 可选。代理发出的 UI 组件的命名定义，每个指向 JS/TS 文件。（langgraph-cli>=0.1.84 起支持） |
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 等字段。 | |
- configurable_headers：定义要排除或包含为运行配置值的请求头。 |
2.2 JavaScript 配置
| 键 | 描述 |
|---|---|
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）：读取时是否刷新 TTL。 | |
- default_ttl（浮点数，分钟为单位，默认无过期）：项目默认寿命。 | |
- sweep_interval_minutes（整数，默认无清理）：检查过期项目的频率。 | |
node_version | 指定 node_version: 20 以使用 LangGraph.js。 |
dockerfile_lines | 在父镜像导入后添加到 Dockerfile 的附加行数组。 |
checkpointer | 检查点配置，包含 ttl 字段，是一个具有以下键的对象： |
- strategy：处理过期检查点的方式（例如，"delete"）。 | |
- sweep_interval_minutes：检查过期检查点的频率（整数，分钟）。 | |
- default_ttl：检查点的默认生存时间（整数，分钟），定义检查点在应用指定策略前保留的时间。 |
2.3 配置示例
Python 示例
基本配置
{
"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：3072openai:text-embedding-3-small：1536openai:text-embedding-ada-002：1536cohere:embed-english-v3.0：1024cohere:embed-english-light-v3.0：384cohere:embed-multilingual-v3.0：1024cohere: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"]
}
}
}
store 配置中的 embed 字段可以引用自定义函数，该函数接受字符串列表并返回嵌入列表。示例实现：
# embeddings.py
def embed_texts(texts: list[str]) -> list[list[float]]:
"""Custom embedding function for semantic search."""
# 使用您首选的嵌入模型实现
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：检查点的默认生存时间（分钟，整数）。
示例：设置 30 天（43200 分钟）默认 TTL：
{
"dependencies": ["."],
"graphs": {
"chat": "./chat/graph.py:graph"
},
"checkpointer": {
"ttl": {
"strategy": "delete",
"sweep_interval_minutes": 10,
"default_ttl": 43200
}
}
}
在此示例中，超过 30 天的检查点将被删除，检查每 10 分钟运行一次。
JavaScript 示例
基本配置
{
"graphs": {
"chat": "./src/graph.ts:graph"
}
}
3. 命令
3.1 Python 命令
基本命令为 langgraph：
langgraph [OPTIONS] COMMAND [ARGS]
3.1.1 dev
描述：
以开发模式运行 LangGraph API 服务器，支持热重载和调试功能。此轻量级服务器无需 Docker 安装，适合开发和测试。状态持久化到本地目录。
注意：
当前 CLI 仅支持 Python >= 3.11。
安装要求：
此命令需要安装 "inmem" 额外依赖：
pip install -U "langgraph-cli[inmem]"
用法：
langgraph dev [OPTIONS]
选项：
| 选项 | 默认值 | 描述 |
|---|---|---|
-c, --config FILE | langgraph.json | 声明依赖、图和环境变量的配置文件路径。 |
--host TEXT | 127.0.0.1 | 服务器绑定的主机。 |
--port INTEGER | 2024 | 服务器绑定的端口。 |
--no-reload | 禁用自动重载。 | |
--n-jobs-per-worker INTEGER | 10 | 每个工作进程的作业数，默认 10。 |
--debug-port INTEGER | 调试器监听的端口。 | |
--wait-for-client | False | 在启动服务器前等待调试器客户端连接到调试端口。 |
--no-browser | 启动服务器时跳过自动打开浏览器。 | |
--studio-url TEXT | https://smith.langchain.com | 连接的 LangGraph Studio 实例 URL。 |
--allow-blocking | False | 不对代码中的同步 I/O 阻塞操作抛出错误。（0.2.6 起支持） |
--tunnel | False | 通过公共隧道（Cloudflare）暴露本地服务器，供远程前端访问，避免 Safari 等浏览器或网络阻止本地连接的问题。 |
--help | 显示命令文档。 |
3.1.2 build
描述：
构建 LangGraph 平台 API 服务器 Docker 镜像。
用法：
langgraph build [OPTIONS]
选项：
| 选项 | 默认值 | 描述 |
|---|---|---|
--platform TEXT | 构建 Docker 镜像的目标平台。例如：langgraph build --platform linux/amd64,linux/arm64。 | |
-t, --tag TEXT | 必填。Docker 镜像的标签。例如：langgraph build -t my-image。 | |
--pull / --no-pull | --pull | 使用最新的远程 Docker 镜像构建。使用 --no-pull 以使用本地构建的镜像运行 LangGraph 平台 API 服务器。 |
-c, --config FILE | langgraph.json | 声明依赖、图和环境变量的配置文件路径。 |
--help | 显示命令文档。 |
3.1.3 up
描述：
启动 LangGraph API 服务器。对于本地测试，需要具有 LangGraph 平台闭测访问权限的 LangSmith API 密钥。生产使用需要许可证密钥。
用法：
langgraph up [OPTIONS]
选项：
| 选项 | 默认值 | 描述 |
|---|---|---|
--wait | 等待服务启动后返回。隐含 --detach。 | |
--postgres-uri TEXT | 本地数据库 | 数据库使用的 Postgres URI。 |
--watch | 文件更改时重启。 | |
--debugger-base-url TEXT | http://127.0.0.1:[PORT] | 调试器访问 LangGraph API 的 URL。 |
--debugger-port INTEGER | 本地拉取调试器镜像并在指定端口提供 UI。 | |
--verbose | 显示更多服务器日志输出。 | |
-c, --config FILE | langgraph.json | 声明依赖、图和环境变量的配置文件路径。 |
-d, --docker-compose FILE | 包含要启动的附加服务的 docker-compose.yml 文件路径。 | |
-p, --port INTEGER | 8123 | 暴露的端口。例如：langgraph up --port 8000。 |
--pull / --no-pull | --pull | 拉取最新镜像。使用 --no-pull 以使用本地构建的镜像运行服务器。例如：langgraph up --no-pull。 |
--recreate / --no-recreate | --no-recreate | 即使配置和镜像未更改也重新创建容器。 |
--help | 显示命令文档。 |
3.1.4 dockerfile
描述：
生成用于构建 LangGraph 平台 API 服务器 Docker 镜像的 Dockerfile。
用法：
langgraph dockerfile [OPTIONS] SAVE_PATH
选项：
| 选项 | 默认值 | 描述 |
|---|---|---|
-c, --config FILE | 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 中。
3.2 JavaScript 命令
基本命令为 langgraphjs 或使用 npx：
npx @langchain/langgraph-cli [OPTIONS] COMMAND [ARGS]
建议使用 npx 以始终使用最新版本的 CLI。
3.2.1 dev
描述：
以开发模式运行 LangGraph API 服务器，支持热重载功能。此轻量级服务器无需 Docker 安装，适合开发和测试。状态持久化到本地目录。
用法：
npx @langchain/langgraph-cli dev [OPTIONS]
选项：
| 选项 | 默认值 | 描述 |
|---|---|---|
-c, --config FILE | langgraph.json | 声明依赖、图和环境变量的配置文件路径。 |
--host TEXT | 127.0.0.1 | 服务器绑定的主机。 |
--port INTEGER | 2024 | 服务器绑定的端口。 |
--no-reload | 禁用自动重载。 | |
--n-jobs-per-worker INTEGER | 10 | 每个工作进程的作业数，默认 10。 |
--debug-port INTEGER | 调试器监听的端口。 | |
--wait-for-client | False | 在启动服务器前等待调试器客户端连接到调试端口。 |
--no-browser | 启动服务器时跳过自动打开浏览器。 | |
--studio-url TEXT | https://smith.langchain.com | 连接的 LangGraph Studio 实例 URL。 |
--allow-blocking | False | 不对代码中的同步 I/O 阻塞操作抛出错误。 |
--tunnel | False | 通过公共隧道（Cloudflare）暴露本地服务器，供远程前端访问，避免浏览器或网络阻止本地连接的问题。 |
--help | 显示命令文档。 |
3.2.2 build
描述：
构建 LangGraph 平台 API 服务器 Docker 镜像。
用法：
npx @langchain/langgraph-cli build [OPTIONS]
选项：
| 选项 | 默认值 | 描述 |
|---|---|---|
--platform TEXT | 构建 Docker 镜像的目标平台。例如：langgraph build --platform linux/amd64,linux/arm64。 | |
-t, --tag TEXT | 必填。Docker 镜像的标签。例如：langgraph build -t my-image。 | |
--no-pull | 使用本地构建的镜像。默认 false，使用最新的远程 Docker 镜像构建。 | |
-c, --config FILE | langgraph.json | 声明依赖、图和环境变量的配置文件路径。 |
--help | 显示命令文档。 |
3.2.3 up
描述：
启动 LangGraph API 服务器。对于本地测试，需要具有 LangGraph 平台闭测访问权限的 LangSmith API 密钥。生产使用需要许可证密钥。
用法：
npx @langchain/langgraph-cli up [OPTIONS]
选项：
| 选项 | 默认值 | 描述 |
|---|---|---|
--wait | 等待服务启动后返回。隐含 --detach。 | |
--postgres-uri TEXT | 本地数据库 | 数据库使用的 Postgres URI。 |
--watch | 文件更改时重启。 | |
-c, --config FILE | langgraph.json | 声明依赖、图和环境变量的配置文件路径。 |
-d, --docker-compose FILE | 包含要启动的附加服务的 docker-compose.yml 文件路径。 | |
-p, --port INTEGER | 8123 | 暴露的端口。例如：langgraph up --port 8000。 |
--no-pull | 使用本地构建的镜像。默认 false，使用最新的远程 Docker 镜像。 | |
--recreate | 即使配置和镜像未更改也重新创建容器。 | |
--help | 显示命令文档。 |
3.2.4 dockerfile
描述：
生成用于构建 LangGraph 平台 API 服务器 Docker 镜像的 Dockerfile。
用法：
npx @langchain/langgraph-cli dockerfile [OPTIONS] SAVE_PATH
选项：
| 选项 | 默认值 | 描述 |
|---|---|---|
-c, --config FILE | 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 中。
4. 总结
- CLI 机制：LangGraph CLI 提供了在本地 Docker 中构建和运行 LangGraph 平台 API 服务器的工具，支持 Python 和 JavaScript 项目，适合开发、测试和生产部署。
- 安装要求：
- 需要安装 Docker 和 CLI 包（Python：
langgraph-cli，JavaScript：@langchain/langgraph-cli）。 - Python 项目需 Python >= 3.11，JavaScript 项目需 Node.js 20。
- 需要安装 Docker 和 CLI 包（Python：
- 配置文件：
- 使用
langgraph.json定义依赖、图、存储、检查点、认证和 HTTP 配置。 - 支持语义搜索（
store.index）、TTL（store.ttl和checkpointer.ttl）和自定义认证（auth）。 - Python 支持更多配置选项（如
python_version、pip_config_file），JavaScript 配置更简洁。
- 使用
- 命令：
dev：开发模式，支持热重载，适合快速迭代。build：构建 Docker 镜像，指定平台和标签。up：启动 API 服务器，支持本地测试和生产部署。dockerfile：生成 Dockerfile，需随langgraph.json更新重新运行。
- 使用建议：
- 在开发中使用
dev命令以利用热重载和调试功能。 - 在生产中，使用
up命令并配置 LangSmith API 密钥或许可证密钥。 - 为存储和检查点配置 TTL 以管理数据生命周期。
- 使用语义搜索和自定义嵌入函数增强
BaseStore功能。 - 确保
langgraph.json与 Dockerfile 保持同步以反映最新配置。
- 在开发中使用
- 注意事项：
- 检查 Docker 是否正确安装和运行。
- Python 的
dev命令需要安装"inmem"额外依赖。 - 生产部署需要 LangGraph 平台许可证。
LangGraph CLI 为开发者提供了灵活的工具来构建和部署 LangGraph API 服务器，适合从快速原型设计到生产环境的各种场景。
参考资料：
- https://langchain-ai.github.io/langgraph/cloud/reference/cli/
