跳到主要内容
LangGraph CLI 是一个命令行工具，用于在本地构建和运行 LangGraph API 服务器。生成的服务器公开了用于运行、线程、助手等的所有 API 端点，并包含支持服务，例如用于检查点和存储的托管数据库。

​
安装

  1. 确保 Docker 已安装（例如，docker --version）。
  2. 安装 CLI 
    pip install langgraph-cli
  3. 验证安装 
    langgraph --help

​
快速命令

命令作用
langgraph dev启动一个轻量级本地开发服务器（无需 Docker），非常适合快速测试。
langgraph build构建用于部署的 LangGraph API 服务器的 Docker 镜像。
langgraph dockerfile根据您的配置生成 Dockerfile，用于自定义构建。
langgraph up在 Docker 中本地启动 LangGraph API 服务器。需要 Docker 运行；本地开发需要 LangSmith API 密钥；生产环境需要许可证。
对于 JS，请使用 npx @langchain/langgraph-cli <command>（如果全局安装，则使用 langgraphjs）。

​
配置文件

LangGraph CLI 需要一个 JSON 配置文件，该文件遵循此 schema。它包含以下属性
LangGraph CLI 默认使用当前目录中的配置文件 langgraph.json。
  • Python
  • JS
键描述
dependencies必需。LangSmith 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 中添加）
image_distro可选。基础镜像的 Linux 发行版。必须是 "debian"、"wolfi"、"bookworm" 或 "bullseye" 之一。如果省略，则默认为 "debian"。在 langgraph-cli>=0.2.11 中可用。
env.env 文件的路径或从环境变量到其值的映射。
store用于为 BaseStore 添加语义搜索和/或生存时间 (TTL) 的配置。包含以下字段
  • index（可选）：用于语义搜索索引的配置，包含 embed、dims 和可选的 fields 字段。
  • ttl（可选）：用于项目过期的配置。一个包含可选字段的对象：refresh_on_read（布尔值，默认为 true）、default_ttl（浮点数，以分钟为单位的生命周期；仅适用于新创建的项目；现有项目不变；默认为永不过期）和 sweep_interval_minutes（整数，检查过期项目的频率，默认为不进行清理）。
ui可选。由代理发出的 UI 组件的命名定义，每个组件指向一个 JS/TS 文件。（在 langgraph-cli==0.1.84 中添加）
python_version3.11、3.12 或 3.13。默认为 3.11。
node_version指定 node_version: 20 以使用 LangGraph.js。
pip_config_filepip 配置文件的路径。
pip_installer（v0.3 中新增） 可选。Python 包安装程序选择器。可设置为 "auto"、"pip" 或 "uv"。从 0.3 版本开始，默认策略是运行 uv pip，这通常可以提供更快的构建速度，同时仍然可以作为直接替代品。在 uv 无法处理您的依赖图或 pyproject.toml 结构的不常见情况下，在此处指定 "pip" 以恢复到以前的行为。
keep_pkg_tools（v0.3.4 中新增） 可选。控制是否在最终镜像中保留 Python 打包工具（pip、setuptools、wheel）。接受的值
  • true：保留所有三个工具（跳过卸载）。
  • false / 省略：卸载所有三个工具（默认行为）。
  • list[str]：要保留的工具名称。每个值必须是“pip”、“setuptools”或“wheel”之一。
。默认情况下，所有三个工具都会被卸载。
dockerfile_lines在从父镜像导入后，要添加到 Dockerfile 的附加行数组。
checkpointer检查点的配置。包含一个 ttl 字段，该字段是一个具有以下键的对象
  • strategy：如何处理过期的检查点（例如，"delete"）。
  • sweep_interval_minutes：检查过期检查点的频率（整数）。
  • default_ttl：检查点的默认生存时间，以分钟为单位（整数）；仅适用于新创建的检查点/线程（现有数据不变）。定义在应用指定策略之前检查点保留多长时间。
httpHTTP 服务器配置，包含以下字段
  • app：自定义 Starlette/FastAPI 应用程序的路径（例如，"./src/agent/webapp.py:app"）。请参阅 自定义路由指南。
  • cors：CORS 配置，包含 allow_origins、allow_methods、allow_headers 等字段。
  • configurable_headers：定义要排除或包含为运行可配置值的请求头。
  • disable_assistants：禁用 /assistants 路由
  • disable_mcp：禁用 /mcp 路由
  • disable_meta：禁用 /ok、/info、/metrics 和 /docs 路由
  • disable_runs：禁用 /runs 路由
  • disable_store：禁用 /store 路由
  • disable_threads：禁用 /threads 路由
  • disable_ui：禁用 /ui 路由
  • disable_webhooks：在所有路由中禁用运行完成时的 webhook 调用
  • mount_prefix：挂载路由的前缀（例如，“/my-deployment/api”）
api_version（v0.3.7 中新增） 要使用的 LangGraph API 服务器的语义版本（例如，"0.3"）。默认为最新版本。请查看服务器 更新日志 以获取每个版本的详细信息。

​
示例

  • Python
  • JS

​
基本配置

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  }
}

​
使用 Wolfi 基础镜像

您可以使用 image_distro 字段指定基础镜像的 Linux 发行版。有效选项包括 debian、wolfi、bookworm 或 bullseye。Wolfi 是推荐选项，因为它提供更小、更安全的镜像。此功能在 langgraph-cli>=0.2.11 中可用。
{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "image_distro": "wolfi"
}

​
为存储添加语义搜索

所有部署都带有 DB 支持的 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"]
    }
  }
}
存储配置中的 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

​
添加自定义身份验证

{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "auth": {
    "path": "./auth.py:auth",
    "openapi": {
      "securitySchemes": {
        "apiKeyAuth": {
          "type": "apiKey",
          "in": "header",
          "name": "X-API-Key"
        }
      },
      "security": [{ "apiKeyAuth": [] }]
    },
    "disable_studio_auth": false
  }
}
有关详细信息，请参阅 身份验证概念指南，并参阅 设置自定义身份验证 指南，以获取实际操作流程。

​
配置存储项的生存时间 (Time-to-Live)

您可以使用 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 分钟）、读取时刷新并每小时清理的示例
{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "memory_agent": "./agent/graph.py:graph"
  },
  "store": {
    "ttl": {
      "refresh_on_read": true,
      "sweep_interval_minutes": 60,
      "default_ttl": 10080
    }
  }
}

​
配置检查点生存时间 (Time-to-Live)

您可以使用 checkpointer 键配置检查点的生存时间 (TTL)。这决定了检查点数据在根据指定策略（例如，删除）自动处理之前保留多长时间。ttl 配置是一个包含以下内容的对象
  • strategy：对过期检查点采取的操作（目前 "delete" 是唯一接受的选项）。
  • sweep_interval_minutes：系统检查过期检查点的频率（以分钟为单位）。
  • default_ttl：检查点的默认生命周期，以分钟为单位。仅适用于部署后创建的检查点/线程；现有数据不会修改。
以下是设置 30 天（43200 分钟）默认 TTL 的示例
{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "checkpointer": {
    "ttl": {
      "strategy": "delete",
      "sweep_interval_minutes": 10,
      "default_ttl": 43200
    }
  }
}
在此示例中，超过 30 天的检查点将被删除，并且检查每 10 分钟运行一次。

​
固定 API 版本

（v0.3.7 中新增）您可以通过使用 api_version 键来固定 LangGraph 服务器的 API 版本。这对于确保您的服务器使用特定版本的 API 非常有用。默认情况下，云部署中的构建使用服务器的最新稳定版本。这可以通过将 api_version 键设置为特定版本来固定。
{
  "$schema": "https://langgra.ph/schema.json",
  "dependencies": ["."],
  "graphs": {
    "chat": "chat.graph:graph"
  },
  "api_version": "0.2"
}

​
命令

用法
  • Python
  • JS
LangGraph CLI 的基本命令是 langgraph。
langgraph [OPTIONS] COMMAND [ARGS]

​
dev

  • Python
  • JS
以开发模式运行 LangGraph API 服务器，具有热重载和调试功能。此轻量级服务器无需 Docker 安装，适用于开发和测试。状态持久化到本地目录。
目前，CLI 仅支持 Python >= 3.11。
安装此命令需要安装“inmem”额外功能：
pip install -U "langgraph-cli[inmem]"
用法
langgraph dev [OPTIONS]
选项
选项默认描述
-c, --config FILElanggraph.json声明依赖项、图和环境变量的配置文件的路径
--host TEXT127.0.0.1服务器绑定的主机
--port INTEGER2024服务器绑定的端口
--no-reload禁用自动重载
--n-jobs-per-worker INTEGER每个工作线程的作业数。默认为 10
--debug-port INTEGER调试器监听的端口
--wait-for-clientFalse在启动服务器之前等待调试器客户端连接到调试端口
--no-browser服务器启动时不自动打开浏览器
--studio-url TEXT要连接的 Studio 实例的 URL。默认为 https://smith.langchain.com
--allow-blockingFalse不要因代码中的同步 I/O 阻塞操作而引发错误（在 0.2.6 中添加）
--tunnelFalse通过公共隧道（Cloudflare）公开本地服务器，用于远程前端访问。这可以避免 Safari 等浏览器或网络阻止 localhost 连接的问题
--help显示命令文档

​
build

  • Python
  • JS
构建 LangSmith 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 运行本地构建的 LangSmith API 服务器镜像。
-c, --config FILElanggraph.json声明依赖项、图和环境变量的配置文件的路径。
--build-command TEXT*要运行的构建命令。在您的 langgraph.json 文件所在的目录中运行。示例：langgraph build --build-command "yarn run turbo build"
--install-command TEXT*要运行的安装命令。在您调用 langgraph build 的目录中运行。示例：langgraph build --install-command "yarn install"
--help显示命令文档。
*仅支持 JS 部署，对 Python 部署没有影响。

​
up

  • Python
  • JS
启动 LangGraph API 服务器。对于本地测试，需要具有 LangSmith 访问权限的 LangSmith API 密钥。生产使用需要许可证密钥。用法
langgraph up [OPTIONS]
选项
选项默认描述
--wait返回之前等待服务启动。暗示 —detach
--base-image TEXTlangchain/langgraph-api用于 LangGraph API 服务器的基础镜像。使用版本标签固定到特定版本。
--image TEXT用于 langgraph-api 服务的 Docker 镜像。如果指定，则跳过构建并直接使用此镜像。
--postgres-uri TEXT本地数据库用于数据库的 Postgres URI。
--watch文件更改时重新启动
--debugger-base-url TEXThttp://127.0.0.1:[PORT]调试器用于访问 LangGraph API 的 URL。
--debugger-port INTEGER在本地拉取调试器镜像并在指定端口上提供 UI
--verbose显示更多服务器日志输出。
-c, --config FILElanggraph.json声明依赖项、图和环境变量的配置文件的路径。
-d, --docker-compose FILE包含要启动的附加服务的 docker-compose.yml 文件的路径。
-p, --port INTEGER8123要公开的端口。示例：langgraph up --port 8000
--pull / --no-pullpull拉取最新镜像。使用 --no-pull 运行本地构建的服务器镜像。示例：langgraph up --no-pull
--recreate / --no-recreateno-recreate即使容器的配置和镜像未更改，也重新创建容器
--help显示命令文档。

​
dockerfile

  • Python
  • JS
生成用于构建 LangSmith API 服务器 Docker 镜像的 Dockerfile。用法
langgraph dockerfile [OPTIONS] SAVE_PATH
选项
选项默认描述
-c, --config FILElanggraph.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 dockerfile 命令会将 langgraph.json 文件中的所有配置转换为 Dockerfile 命令。使用此命令时，您必须在更新 langgraph.json 文件时重新运行它。否则，当您构建或运行 dockerfile 时，您的更改将不会反映出来。
在 GitHub 上编辑此页面源文件。
以编程方式连接这些文档到 Claude、VSCode 等，通过 MCP 获取实时答案。
© . This site is unofficial and not affiliated with LangChain, Inc.