LangGraph CLI¶

基本配置¶

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

使用 Wolfi 基础镜像¶

您可以使用 `image_distro` 字段指定基础镜像的 Linux 发行版。有效选项是 `debian` 或 `wolfi`。Wolfi 是推荐选项，因为它提供了更小、更安全的镜像。此功能在 `langgraph-cli>=0.2.11` 中可用。

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

为存储添加语义搜索¶

所有部署都附带一个 DB 支持的 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": ["$"]
    }
  }
}

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

如果您想使用自定义嵌入函数进行语义搜索，可以传入自定义嵌入函数的路径

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

LangGraph CLI 的基本命令是 `langgraph`。

langgraph [OPTIONS] COMMAND [ARGS]

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

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

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

在开发模式下运行 LangGraph API 服务器，支持热重载和调试功能。此轻量级服务器无需 Docker 安装，适用于开发和测试。状态数据将持久化到本地目录。

安装

此命令需要安装“inmem”额外功能

pip install -U "langgraph-cli[inmem]"

用法

langgraph dev [OPTIONS]

选项

在开发模式下运行 LangGraph API 服务器，支持热重载功能。此轻量级服务器无需 Docker 安装，适用于开发和测试。状态数据将持久化到本地目录。

用法

npx @langchain/langgraph-cli dev [OPTIONS]

选项

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

用法

langgraph build [OPTIONS]

选项

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

用法

npx @langchain/langgraph-cli build [OPTIONS]

选项

启动 LangGraph API 服务器。用于本地测试时，需要拥有 LangGraph 平台封闭测试版访问权限的 LangSmith API 密钥。生产环境使用需要许可证密钥。

用法

langgraph up [OPTIONS]

选项

启动 LangGraph API 服务器。用于本地测试时，需要拥有 LangGraph 平台封闭测试版访问权限的 LangSmith API 密钥。生产环境使用需要许可证密钥。

用法

npx @langchain/langgraph-cli up [OPTIONS]

选项

生成用于构建 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 平台 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