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

LangGraph 命令行界面（CLI）

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

1. 安装

2. 配置文件

LangGraph CLI 要求使用 JSON 配置文件，遵循以下模式。配置文件默认位于当前目录的 langgraph.json 文件中。

2.1 Python 配置

2.2 JavaScript 配置

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

选项：

3.1.2 build

描述： 构建 LangGraph 平台 API 服务器 Docker 镜像。

用法：

langgraph build [OPTIONS]

选项：

3.1.3 up

描述： 启动 LangGraph API 服务器。对于本地测试，需要具有 LangGraph 平台闭测访问权限的 LangSmith API 密钥。生产使用需要许可证密钥。

用法：

langgraph up [OPTIONS]

选项：

3.1.4 dockerfile

描述： 生成用于构建 LangGraph 平台 API 服务器 Docker 镜像的 Dockerfile。

用法：

langgraph dockerfile [OPTIONS] SAVE_PATH

选项：

示例：

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]

选项：

3.2.2 build

描述： 构建 LangGraph 平台 API 服务器 Docker 镜像。

用法：

npx @langchain/langgraph-cli build [OPTIONS]

选项：

3.2.3 up

描述： 启动 LangGraph API 服务器。对于本地测试，需要具有 LangGraph 平台闭测访问权限的 LangSmith API 密钥。生产使用需要许可证密钥。

用法：

npx @langchain/langgraph-cli up [OPTIONS]

选项：

3.2.4 dockerfile

描述： 生成用于构建 LangGraph 平台 API 服务器 Docker 镜像的 Dockerfile。

用法：

npx @langchain/langgraph-cli dockerfile [OPTIONS] SAVE_PATH

选项：

示例：

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。
• 配置文件：
  • 使用 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/