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

向存储中添加语义搜索¶

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

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

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

{
  "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：检查点的默认生存时间，以分钟为单位。

以下是设置 30 天默认 TTL（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