LangGraph 命令行接口¶

LangGraph 的命令行接口包括用于在 Docker 中本地构建和运行 LangGraph Cloud API 服务器的命令。在开发和测试过程中，您可以使用 CLI 将本地 API 服务器部署为 Studio 桌面应用程序的替代方案。

安装¶

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

安装 CLI 包：

PythonJS

pip install langgraph-cli

# 通过 Homebrew 安装
brew install langgraph-cli

npx @langchain/langgraph-cli

# 全局安装，将作为 `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 服务器的依赖项数组。依赖项可以是以下之一：(1) `"."`，表示查找本地 Python 包，(2) `pyproject.toml`、`setup.py` 或 `requirements.txt` 文件在应用目录 `"./local_package"` 中，或 (3) 包名。
`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 添加语义搜索的配置。包含以下字段： `index`：语义搜索索引配置，包含以下字段： `embed`：嵌入提供者（例如，“openai:text-embedding-3-small”）或自定义嵌入函数的路径 `dims`：嵌入模型的维度大小。用于初始化向量表。 `fields`（可选）：要索引的字段列表。默认为 `["$"]`，表示索引整个文档。可以是特定字段，如 `["text", "summary", "some.value"]`
`python_version`	`3.11` 或 `3.12`。默认为 `3.11`。
`node_version`	指定 `node_version: 20` 以使用 LangGraph.js。
`pip_config_file`	`pip` 配置文件的路径。
`dockerfile_lines`	从父镜像导入后要添加到 Dockerfile 的额外行数组。

键	描述
`graphs`	必需。从图 ID 到定义编译图或生成图的函数的路径的映射。示例： `./src/graph.ts:variable`，其中 `variable` 是 `CompiledStateGraph` 的实例 `./src/graph.ts:makeGraph`，其中 `makeGraph` 是一个接受配置字典 (`LangGraphRunnableConfig`) 并创建 `StateGraph` / `CompiledStateGraph` 实例的函数。
`env`	`.env` 文件的路径或环境变量到其值的映射。
`store`	为 BaseStore 添加语义搜索的配置。包含以下字段： `index`：语义搜索索引配置，包含以下字段： `embed`：嵌入提供者（例如，“openai:text-embedding-3-small”）或自定义嵌入函数的路径 `dims`：嵌入模型的维度大小。用于初始化向量表。 `fields`（可选）：要索引的字段列表。默认为 `["$"]`，表示索引整个文档。可以是特定字段，如 `["text", "summary", "some.value"]`
`node_version`	指定 `node_version: 20` 以使用 LangGraph.js。
`dockerfile_lines`	从父镜像导入后要添加到 Dockerfile 的额外行数组。

示例¶

PythonJS

基本配置¶

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

为存储添加语义搜索¶

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

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]]:
    """自定义嵌入函数用于语义搜索。"""
    # 使用你首选的嵌入模型实现
    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
  }
}

详情请参阅身份验证概念指南，以及设置自定义身份验证指南，了解实际操作步骤。

基本配置¶

{
  "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，并适合开发和测试。状态将持久化到本地目录中。

Note

目前，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
`--debug-port INTEGER`		调试器监听的端口
`--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`		每个工作线程的任务数，默认为 10
`--debug-port INTEGER`		调试器监听的端口
`--help`		显示命令文档

`build`¶

PythonJS

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

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

`up`¶

PythonJS

启动 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`		显示命令文档。

启动 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`		显示命令文档。

`dockerfile`¶

PythonJS

生成用于构建 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 时将不会反映出来。

生成用于构建 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 时将不会反映出来。

LangGraph 命令行接口¶

安装¶

配置文件¶

示例¶

基本配置¶

为存储添加语义搜索¶

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

添加自定义身份验证¶

基本配置¶

命令¶

dev¶

build¶

up¶

dockerfile¶

Comments

`dev`¶

`build`¶

`up`¶

`dockerfile`¶