LangGraph CLI¶

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

安装¶

确保已安装 Docker (例如 docker --version)。

安装 CLI 包

PythonJS

pip install langgraph-cli

# Install via Homebrew
brew 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 服务器的依赖项数组。依赖项可以是以下之一：（1）`"."`，它将查找本地 Python 包；（2）应用程序目录 `"./local_package"` 中的 `pyproject.toml`、`setup.py` 或 `requirements.txt`；或（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 的附加行数组。
`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` 等字段。

键	描述
`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"]
缺少指定字段的文档仍将被存储，但这些字段将没有嵌入
您仍然可以使用 index 参数在 put 时覆盖要在特定项目上嵌入的字段

{
  "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."""
    # 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
  }
}

有关详细信息，请参阅身份验证概念指南，有关实际演练过程，请参阅设置自定义身份验证指南。

基本配置¶

{
  "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`		调试器监听的端口
`--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`		调试器监听的端口
`--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 封闭 Beta 版访问权限的 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 封闭 Beta 版访问权限的 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¶

安装¶

配置文件¶

示例¶

基本配置¶

向存储添加语义搜索¶

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

添加自定义身份验证¶

基本配置¶

命令¶

dev¶

build¶

up¶

dockerfile¶

评论

`dev`¶

`build`¶

`up`¶

`dockerfile`¶