LangGraph CLI¶

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

安装¶

确保 Docker 已安装（例如 docker --version）。

安装 CLI 包

PythonJS

pip install langgraph-cli

npx @langchain/langgraph-cli

# Install globally, will be available as `langgraphjs`
npm install -g @langchain/langgraph-cli

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

配置文件¶

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

注意

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

PythonJS

键	描述
`dependencies`	必需。LangGraph Cloud 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` 或 `langchain/langgraphjs-api`。使用此项将您的构建固定到特定版本的 langgraph API，例如 `"langchain/langgraph-server:0.2"`。更多详情请参阅https://hub.docker.com/r/langchain/langgraph-server/tags。（添加于 `langgraph-cli==0.2.8`）
`env`	`.env` 文件的路径或环境变量与其值的映射。
`store`	配置，用于为 BaseStore 添加语义搜索和/或生存时间 (TTL)。包含以下字段 `index` (可选)：语义搜索索引配置，包含字段 `embed`、`dims` 和可选的 `fields`。 `ttl` (可选)：项目过期配置。一个对象，包含可选字段：`refresh_on_read`（布尔值，默认为 `true`）、`default_ttl`（浮点数，寿命以分钟为单位，默认为不过期）和 `sweep_interval_minutes`（整数，检查过期项目的频率，默认为不进行清理）。
`ui`	可选。agent 发出的 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`	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`：定义哪些请求头作为运行的可配置值被排除或包含。

键	描述
`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`	checkpointer 的配置。包含一个 `ttl` 字段，它是一个包含以下键的对象 `strategy`：如何处理过期的检查点（例如，`"delete"`）。 `sweep_interval_minutes`：检查过期检查点的频率（整数）。 `default_ttl`：检查点的默认生存时间，以分钟为单位（整数）。定义在应用指定策略之前检查点保留的时间。

示例¶

PythonJS

基本配置¶

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

为存储添加语义搜索¶

所有部署都带有基于数据库的 BaseStore。将“index”配置添加到您的 langgraph.json 将在您部署的 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]]:
    """Custom embedding function for semantic search."""
    # Implementation using your preferred embedding model
    return [[0.1, 0.2, ...] for _ in texts]  # dims-dimensional vectors

添加自定义认证¶

{
  "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 [OPTIONS] COMMAND [ARGS]

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

npx @langchain/langgraph-cli [OPTIONS] COMMAND [ARGS]

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

`dev`¶

PythonJS

在开发模式下运行 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`		每个 worker 的作业数。默认为 10
`--debug-port INTEGER`		调试器监听的端口
`--wait-for-client`	`False`	等待调试器客户端连接到调试端口后再启动服务器
`--no-browser`		启动服务器时跳过自动打开浏览器
`--studio-url TEXT`		要连接的 LangGraph Studio 实例的 URL。默认为 https://smith.langchain.com
`--allow-blocking`	`False`	不对代码中的同步 I/O 阻塞操作引发错误（添加于 `0.2.6`）
`--tunnel`	`False`	通过公共隧道 (Cloudflare) 暴露本地服务器以供远程前端访问。这避免了 Safari 等浏览器或网络阻止 localhost 连接的问题
`--help`		显示命令文档

在开发模式下运行 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`		每个 worker 的作业数。默认为 10
`--debug-port INTEGER`		调试器监听的端口
`--wait-for-client`	`False`	等待调试器客户端连接到调试端口后再启动服务器
`--no-browser`		启动服务器时跳过自动打开浏览器
`--studio-url TEXT`		要连接的 LangGraph Studio 实例的 URL。默认为 https://smith.langchain.com
`--allow-blocking`	`False`	不对代码中的同步 I/O 阻塞操作引发错误
`--tunnel`	`False`	通过公共隧道 (Cloudflare) 暴露本地服务器以供远程前端访问。这避免了浏览器或网络阻止 localhost 连接的问题。
`--help`		显示命令文档

`build`¶

PythonJS

构建 LangGraph Cloud 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 Cloud API 服务器。
`-c, --config FILE`	`langgraph.json`	声明依赖项、图和环境变量的配置文件路径。
`--help`		显示命令文档。

构建 LangGraph Cloud 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`		显示命令文档。

`up`¶

PythonJS

启动 LangGraph API 服务器。对于本地测试，需要一个具有 LangGraph Cloud 封闭测试权限的 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`		显示命令文档。

启动 LangGraph API 服务器。对于本地测试，需要一个具有 LangGraph Cloud 封闭测试权限的 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`		显示命令文档。

`dockerfile`¶

PythonJS

生成用于构建 LangGraph Cloud 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 时，您的更改将不会反映出来。

生成用于构建 LangGraph Cloud 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 时，您的更改将不会反映出来。

LangGraph CLI¶

安装¶

配置文件¶

示例¶

基本配置¶

为存储添加语义搜索¶

使用自定义嵌入函数的语义搜索¶

添加自定义认证¶

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

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

基本配置¶

命令¶

dev¶

build¶

up¶

dockerfile¶

评论

`dev`¶

`build`¶

`up`¶

`dockerfile`¶