【LangGraph】CLI（命令行界面）：供了用于在本地 Docker 中构建和运行 LangGraph 平台 API 服务器的命令_langgraph cli

技术文档

LangGraph 命令行界面（CLI）

LangGraph 命令行界面（CLI）提供了用于在本地 Docker 中构建和运行 LangGraph 平台 API 服务器的命令。对于开发和测试，您可以使用 CLI 部署本地 API 服务器。

1. 安装

确保已安装 Docker（例如，运行 docker --version 检查）。

安装 CLI 包：
Python：

pip install langgraph-cli

JavaScript：

npx @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：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\"] } }}

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

# embeddings.pydef 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.11ADD ./pipconf.txt /pipconfig.txtRUN PIP_CONFIG_FILE=/pipconfig.txt PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt langchain_community langchain_anthropic langchain_openai wikipedia scikit-learnADD ./graphs /deps/__outer_graphs/srcRUN set -ex && \\ for line in \'[project]\' \\ \'name = \"graphs\"\' \\ \'version = \"0.1\"\' \\ \'[tool.setuptools.package-data]\' \\ \'\"*\" = [\"**/*\"]\'; do \\ echo \"$line\" >> /deps/__outer_graphs/pyproject.toml; \\ doneRUN 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:20ADD . /deps/agentRUN cd /deps/agent && yarn installENV LANGSERVE_GRAPHS=\'{\"agent\":\"./src/react_agent/graph.ts:graph\"}\'WORKDIR /deps/agentRUN (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。
配置文件：
- 使用 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/

【LangGraph】CLI（命令行界面）：供了用于在本地 Docker 中构建和运行 LangGraph 平台 API 服务器的命令_langgraph cli

LangGraph 命令行界面（CLI）

1. 安装

2. 配置文件

2.1 Python 配置

2.2 JavaScript 配置

2.3 配置示例

Python 示例

基本配置

为存储添加语义搜索

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

添加自定义认证

配置存储项目生存时间（TTL）

配置检查点生存时间（TTL）

JavaScript 示例

基本配置

3. 命令

3.1 Python 命令

3.1.1 `dev`

3.1.2 `build`

3.1.3 `up`

3.1.4 `dockerfile`

3.2 JavaScript 命令

3.2.1 `dev`

3.2.2 `build`

3.2.3 `up`

3.2.4 `dockerfile`

4. 总结

公告

DeepSeek全套部署资料免费下载

免费可商用字体批量下载

标签

【LangGraph】CLI（命令行界面）：供了用于在本地 Docker 中构建和运行 LangGraph 平台 API 服务器的命令_langgraph cli

LangGraph 命令行界面（CLI）

1. 安装

2. 配置文件

2.1 Python 配置

2.2 JavaScript 配置

2.3 配置示例

Python 示例

基本配置

为存储添加语义搜索

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

添加自定义认证

配置存储项目生存时间（TTL）

配置检查点生存时间（TTL）

JavaScript 示例

基本配置

3. 命令

3.1 Python 命令

3.1.1 dev

3.1.2 build

3.1.3 up

3.1.4 dockerfile

3.2 JavaScript 命令

3.2.1 dev

3.2.2 build

3.2.3 up

3.2.4 dockerfile

4. 总结

相关问题

公告

DeepSeek全套部署资料免费下载

免费可商用字体批量下载

标签

3.1.1 `dev`

3.1.2 `build`

3.1.3 `up`

3.1.4 `dockerfile`

3.2.1 `dev`

3.2.2 `build`

3.2.3 `up`

3.2.4 `dockerfile`