Langflow LFX 实战指南：用 lfx CLI 以轻量、无状态方式运行与托管 AI Flow

LFX（Langflow Executor）是 Langflow 生态中的独立命令行工具，它从 Flow JSON 文件出发，以极少依赖、无数据库的方式执行（lfx run）或托管（lfx serve）流程，并可作为 MCP Server 暴露给任意 MCP 客户端。读完本篇，你将掌握 LFX 的三种安装方式、lfx serve 完整部署流程（含 API 鉴权、多 Worker、凭证隔离）、lfx run 的多种输入形态（文件/stdin/内联 JSON/Python 脚本）、请求与响应 Schema 的全部字段，以及 NoopSession、可插拔服务等源码级实现原理。

什么是 LFX：无状态的 Flow 执行器

LFX 的定位是「命令行为主、依赖最小」的 Flow 执行器。用它运行 Flow 的体验类似于在 Langflow 中开启 --backend-only 环境变量运行流程，但更轻——因为完全不需要安装 Langflow 主包及其全部依赖。

实现「轻量」的关键在于 LFX 对所有需要持久化状态的操作统一使用一个空操作（no-op）数据库会话接口 NoopSession。从源码实现看，NoopSession 完整模拟了 SQLAlchemy 异步 Session 的 API 表面——add/commit/rollback/execute/query/close/get/exec 全部为空操作，exec 返回的 _NoopResult 的 first()/all()/one_or_none() 分别返回 None/[]/None，连 no_autoflush 上下文管理器和 is_active 属性也都有对应桩实现。这保证了依赖「数据库会话」的代码路径可以正常调用而不报错，但：

• 使用 LFX 时不存在 langflow.db 数据库文件；
• 通过 API 运行 Flow 没问题，但任何依赖 Langflow 数据库的有状态操作（保存 Flow、存储消息、用户管理）都不会持久化；
• 依赖 langflow.db 的操作无法像在完整 Langflow 应用中那样工作。

另外一个值得注意的设计是：Memory 操作在调用时（call time）而非导入时（import time）派发。如果 langflow 包安装在与 lfx 相同的 Python 环境中且注册了真实数据库服务，Memory 操作会被路由到完整的 langflow.memory 实现。这只适用于 lfx 作为 Python 库嵌入运行中的 Langflow Server 的场景，运行 lfx run 或 lfx serve 命令行时不生效。

命令总览

LFX 提供两类命令。运行时命令（本文档覆盖范围）：

命令	说明
lfx serve	将一个或多个 Flow 托管为 FastAPI 端点，路由为 /flows/{flow_id}/run
lfx run	本地执行 Flow 并将结果流式输出到 stdout
lfx-mcp	启动 MCP Server，连接运行中的 Langflow 实例

Flow DevOps SDK 命令（面向远程实例的流程化开发运维）：

命令	说明
lfx init	脚手架生成带版本管理与 CI 模板的 Flow 项目
lfx login	对远程 Langflow 实例校验凭证
lfx create	从内置或自定义模板创建新 Flow JSON
lfx validate	推送前校验 Flow JSON
lfx requirements	根据 Flow 的组件依赖生成 requirements.txt
lfx status	比对本地 Flow 文件与远程实例的差异
lfx push	按稳定 ID 推送 Flow 到远程实例
lfx pull	从远程实例拉取 Flow 到本地文件
lfx export	规范化 Flow JSON，便于产生干净的 git diff

从 CLI 入口源码 src/lfx/src/lfx/main.py 可以看到，lfx 是一个 Typer 应用，命令按功能分组注册：setup、observability、prewarm、authoring（init/create/validate 等）、upgrade、extension、running（run/serve）、remote（login/push/pull/status）——这也解释了 README 中两类命令为何能在同一个 lfx 入口下共存。

前置条件与安装

前置条件：

• 安装 Python（3.10 及以上；从 pyproject.toml 看，当前 lfx 版本要求 >=3.10,<3.15）；
• 安装 uv 包管理器（用于 uv run / uvx 方式运行）；
• 准备一个 Flow JSON 文件。例如使用仓库中的 Simple Agent 起始模板，其位于 [src/backend/base/langflow/initial_setup/starter_projects/Simple Agent.json](https://gitcode.com/GitHub_Trending/la/langflow/blob/48aac8b7445a009132b3c5ce16412ec7d8e2c82f/src/backend/base/langflow/initial_setup/starter_projects/Simple Agent.json?utm_source=gitcode_repo_files)，可以直接复制该文件作为 simple-agent-flow.json；
• 准备模型提供方 API Key（示例使用 OpenAI，需 OpenAI API Key）；
• 准备 Langflow API Key：LFX 场景下可以本地生成安全令牌（见下文），也可以经由 Langflow 服务器 UI 或 CLI 创建。

如果已安装 Langflow OSS 1.6 及以上版本，lfx 已随包附带，可直接使用。

方式一：克隆仓库源码运行

git clone https://github.com/langflow-ai/langflow
cd langflow/src/lfx

在该目录下即可用 uv run lfx 执行命令（后续 lfx serve/lfx run 章节均以此形式演示）。

方式二：从 PyPI 安装

uv venv lfx-venv
source lfx-venv/bin/activate

uv pip install lfx          # 稳定版
uv pip install --pre lfx    # 最新 nightly（预发布）版

方式三：免安装（uvx）

export LANGFLOW_API_KEY="sk..."
uvx lfx serve simple-agent-flow.json

uvx 会在临时环境中下载并运行 LFX，无需永久安装；同一环境中也可以直接 lfx run 运行流程。

从 pyproject.toml 的依赖声明可以看到「引擎精简」的设计思路：pip install lfx 只包含执行引擎（langchain-core、fastapi、uvicorn、typer、networkx 等基础依赖），默认不携带任何组件 bundle；如需长尾的供应商组件，可安装 lfx[bundles]（拉取 lfx-bundles[all]），此外还有 lfx[otel]（OpenTelemetry 可观测性导出）、lfx[sandbox]（QEMU 硬件隔离执行后端，要求 Python >= 3.12）等可选 extra。gunicorn 与 a2wsgi 仅在非 Windows 平台安装——多 Worker 能力基于 gunicorn，Windows 上会回退到 uvicorn 并拒绝 gunicorn 专用参数。

使用 lfx serve 托管 Simple Agent Flow

lfx serve 启动一个 FastAPI 服务器来托管一个或多个 Flow：支持从文件或目录在启动时加载，也可以以空注册表启动、再通过 API 上传 Flow。运行后，Flow 可通过 POST /flows/{flow_id}/run 访问。它接受 .json Flow 文件或 .py Python 脚本（与 lfx run 相同），也支持通过 --flow-json 传入内联 JSON 或通过 --stdin 管道输入。

由于 lfx serve 可能创建公开可访问的 FastAPI 服务器，API Key 是强制要求。以下示例使用 Agent 组件内置的 OpenAI 模型，需要 OpenAI API Key；如需其他提供方，请相应修改模型提供方、模型名与凭证。

第 1 步：生成 Langflow API Key。 对 LFX 而言，本地生成一个安全令牌即可作为 LANGFLOW_API_KEY：

uv run python -c "import secrets; print(secrets.token_urlsafe(32))"

这与通过 Langflow 服务器 UI/CLI 创建并入库的 API Key 不同——LFX 只需要一个安全字符串来鉴权请求，不涉及任何数据库。

第 2 步：配置环境变量，二选一：

.env 文件方式（LANGFLOW_API_KEY 必填，此处假设 Flow 需要 OpenAI Key）：

LANGFLOW_API_KEY="sk..."
OPENAI_API_KEY="sk-..."

或在启动服务器的同一终端会话中导出变量（必须在服务器启动前声明才能被读取）：

export LANGFLOW_API_KEY="sk..."
export OPENAI_API_KEY="sk-..."

第 3 步：安装 Flow 依赖。 如果已安装 Langflow 或从源码 src/lfx 运行，依赖已齐备。若使用 PyPI 独立版 lfx 或 uvx，需手动安装 Flow 中组件所需依赖。查找流程：先跑一次 lfx run（见下节），LFX 会在错误信息中报告缺失依赖，再逐一安装。以 Simple Agent 模板为例：

uv pip install "langchain~=0.3.23" "langchain-core<1.0.0" "langchain-community" "langchain-openai" "langchain-text-splitters" beautifulsoup4 lxml requests

第 4 步：启动服务器：

# .env 文件方式（假设 Flow 文件与 .env 在当前目录）
uv run lfx serve simple-agent-flow.json --env-file .env
uv run lfx serve simple-agent-flow.json --env-file /path/to/.env   # .env 在其他位置

# 或已导出变量时直接启动（自动拾取环境中的值）
uv run lfx serve simple-agent-flow.json

如需更换变量值，需停服、重新导出、再启动。

第 5 步：记录 flow_id。 启动输出形如：

 LFX Server
 Flow loaded: simple-agent-flow.json (c1dab29d-3364-58ef-8fef-99311d32ee42)
 Server:      http://127.0.0.1:8000
 Run flows at: POST /flows/{flow_id}/run
 API key:     x-api-key header or ?x-api-key= query parameter

第 6 步：新终端中设置变量并测试：

export LANGFLOW_API_KEY="sk..."
export FLOW_ID="c1dab29d-3364-58ef-8fef-99311d32ee42"

curl -X POST http://localhost:8000/flows/$FLOW_ID/run \
  -H "Content-Type: application/json" \
  -H "x-api-key: $LANGFLOW_API_KEY" \
  -d '{"input_value": "Hello, world!"}'

成功响应示例：

{
  "result": "Hello world! 👋\n\nHow can I help you today? ...",
  "success": true,
  "logs": "\n\n> Entering new None chain...\nHello world! 👋...\n\n> Finished chain.\n",
  "type": "message",
  "component": "Chat Output"
}

至此，Flow 已成为一个轻量 API 端点——调用方无需安装 Langflow，也无需配置自己的 LLM 提供方 Key（凭证由服务端环境持有）。若要对外公开，可配合 ngrok 之类隧道服务或部署到公有云。

HTTP 端点

所有 /flows/{flow_id} 路由均要求 x-api-key 请求头或 ?x-api-key= 查询参数：

端点	方法	说明
/flows	GET	列出所有已托管 Flow 及其元数据
/flows/upload/	POST	上传 Flow JSON 到注册表（接受完整 Langflow 导出格式）
/flows/{flow_id}/run	POST	运行 Flow，返回单一响应
/flows/{flow_id}/stream	POST	运行 Flow，以 SSE 流式输出
/flows/{flow_id}/info	GET	返回 Flow 元数据（标题、描述、输入/输出类型）
/health	GET	全局健康检查，返回 {"status": "ok"}
/docs	GET	自动生成的 OpenAPI/Swagger UI

请求体 Schema

POST /flows/{flow_id}/run：

{
  "input_value": "Your message here",
  "session_id": "optional-conversation-id"
}

session_id 可选；设置后，Agent 与 Memory 组件会基于它跨多次调用维护会话历史。缺省时每个请求生成新的会话 ID。

POST /flows/{flow_id}/stream 的完整字段：

{
  "input_value": "Your message here",
  "input_type": "chat",
  "output_type": "chat",
  "output_component": null,
  "session_id": "optional-conversation-id",
  "tweaks": {"ComponentName": {"param": "value"}}
}

字段	默认值	说明
input_value	—	必填，传入 Flow 的输入
input_type	"chat"	输入类型：chat 或 text
output_type	"chat"	输出类型：chat、text、debug 或 any
output_component	null	按名称将输出固定到特定组件
session_id	null	跨请求保持记忆连续性的会话 ID
tweaks	null	按请求覆盖参数：键为组件名，值为参数覆盖字典，无需改动 JSON 即可参数化 Flow

响应 Schema

注意 LFX Server 的响应 Schema 与 Langflow API /run 端点的 Schema 不同。/flows/{flow_id}/run 返回：

{
  "result": "string",      // Flow 执行产生的输出结果
  "success": true,         // 执行是否成功
  "logs": "string",        // 执行过程捕获的日志
  "type": "message",      // 结果类型
  "component": "string"   // 产生结果的组件（如 "Chat Output"）
}

/stream 端点以 SSE 返回相同字段，每个组件输出对应一个事件。

启动时加载多个 Flow

可以传入目录、多个文件路径或两者混合，每个 Flow 以各自 ID 注册：

# 托管目录内所有 .json（仅顶层，不递归）
uv run lfx serve flows/

# 托管指定文件
uv run lfx serve flow-a.json flow-b.json

# 目录与文件混合
uv run lfx serve flows/ extra-flow.json

单 Worker 模式下也支持 Python 脚本 Flow：uv run lfx serve my_flow.py。

空注册表启动与动态上传

不提供 Flow 路径时，lfx serve 以空注册表启动，随后可通过 API 上传：

uv run lfx serve --env-file .env

# 上传 Flow JSON（格式即 Langflow UI "Export" 按钮导出的完整格式）
curl -X POST http://localhost:8000/flows/upload/ \
  -H "x-api-key: $LANGFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d @my-flow.json

# 上传并替换相同 ID 的已有 Flow
curl -X POST "http://localhost:8000/flows/upload/?replace=true" \
  -H "x-api-key: $LANGFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d @my-flow.json

上传已注册 ID 的 Flow 且未带 replace=true 时，服务器返回 409 Conflict。

多 Worker 部署

--workers N 启动多个 uvicorn Worker 进程，--flow-dir 让所有 Worker 指向共享目录以托管同一组 Flow：

# 4 个 worker，Flow 经本地临时目录共享
uv run lfx serve flows/ --workers 4 --flow-dir /tmp/lfx-flows

# 跨 Pod 共享（Kubernetes PVC 或类似网络卷）
uv run lfx serve flows/ --workers 4 --flow-dir /mnt/shared-flows

工作机制：

• 启动时，每个 Flow 文件以 {flow_id}.json 持久化到 --flow-dir；
• POST /flows/upload/ 的上传同样写入 --flow-dir，下次请求时对所有 Worker 可见；
• 删除会跨 Worker 传播：每个 Worker 在下次访问该 Flow 时检测到文件缺失即返回 404；
• 未设置 --flow-dir 时，每个 Worker 维护独立的内存注册表，上传只对收到请求的那个 Worker 生效——此时 --workers > 1 会打印警告。

注意：--workers > 1 搭配 --flow-dir 不支持 .py 脚本 Flow——Python 图无法序列化到文件系统存储。

从 src/lfx/src/lfx/cli/serve_app.py 可以看到鉴权与 Worker 间配置的落地方式：API Key 名为 x-api-key，同时支持请求头与查询参数（FastAPI 的 APIKeyHeader + APIKeyQuery），Key 在应用启动时一次性快照到 app.state，避免每请求实时读 os.environ；多 Worker 的配置（flow 目录、no-env-fallback、重置环境变量开关、启动路径等）通过 LFX_SERVE_* 前缀的环境变量传递给 gunicorn fork 出的 Worker 进程。

凭证隔离：--no-env-fallback（实验性）

默认情况下，lfx serve 从进程环境（os.environ）解析组件凭证，多租户部署意味着所有请求共享同一套凭证。--no-env-fallback 关闭进程环境回退，凭证必须在请求体的 global_vars 字段中按请求提供：

uv run lfx serve my-flow.json --no-env-fallback --env-file .env

curl -X POST http://localhost:8000/flows/$FLOW_ID/run \
  -H "Content-Type: application/json" \
  -H "x-api-key: $LANGFLOW_API_KEY" \
  -d '{
    "input_value": "Hello world",
    "global_vars": {
      "LANGFLOW_REQUEST_VARIABLES": {
        "OPENAI_API_KEY": "sk-per-request-key"
      }
    }
  }'

LANGFLOW_REQUEST_VARIABLES 中的凭证通过 Python contextvars 限定在当前请求作用域，Langflow 内置组件不会将其写入 os.environ，因此不会泄漏到同一 Worker 上的其他并发请求；显式写 os.environ 的自定义组件不在此保证范围内。

serve_app.py 中还有两层配套机制：全局 asyncio.Semaphore(1) 保证每个 Worker 同一时刻只跑一个 Flow（串行化环境敏感的执行段），--reset-environ（默认关闭）则在执行前快照 os.environ、执行后按差异恢复，确保热 Worker 上前一请求的环境改动不会污染后一请求。

启动时检查/升级 Flow 兼容性

--upgrade-flow 在托管前检查 Flow 与当前 LFX 版本的兼容性：

# 任一组件不兼容则在启动时失败
uv run lfx serve my-flow.json --upgrade-flow=check

# 在内存中应用安全升级后再启动
uv run lfx serve my-flow.json --upgrade-flow=safe

lfx serve 完整选项表

选项	说明
--check-variables / --no-check-variables	检查全局变量的环境兼容性。默认开启检查
--env-file	包含环境变量的 .env 文件路径
--flow-dir	跨 Worker 共享的文件系统 Flow 存储目录；设置后启动 Flow 与上传都会持久化于此
--flow-json	以内联字符串传入 Flow JSON，如 uv run lfx serve --flow-json '{...}'
--host、-h	绑定主机，默认 127.0.0.1
--log-level	日志级别：debug/info/warning/error/critical，默认 warning
--no-env-fallback / --env-fallback	禁用进程环境凭证回退，配合按请求 LANGFLOW_REQUEST_VARIABLES 使用。默认 --env-fallback
--port、-p	绑定端口，默认 8000
--stdin	从 stdin 读取 Flow JSON，如 cat flow.json | uv run lfx serve --stdin
--max-requests	gunicorn（Unix、--workers > 1）下每 N 个请求回收一次 Worker 以限制内存，默认约每 1000 次（10% 抖动）；0 禁用、1 每请求回收。属于 Worker 卫生机制而非按请求隔离；Windows 上不生效
--reset-environ / --no-reset-environ	每次 Flow 运行前后快照/恢复 os.environ，防止请求间环境改动或请求级凭证泄漏（任意 Worker、任意平台的严格按请求隔离机制）。默认关闭
--use-sync-workers / --use-async-workers	仅多 Worker（Unix）。gunicorn 阻塞式 sync worker 每个 Worker 同时只服务一个请求，内核会把新请求路由到空闲 Worker；配合 --max-requests 1 即另一套严格的按请求隔离（每请求新进程）。经 a2wsgi 桥接（lfx 在 Unix 上自带）。默认异步 Worker
--timeout	Worker 超时秒数（gunicorn，Unix，--workers > 1），超时 Worker 被杀并重启；长流程尤其配合 --use-sync-workers 时应调大，默认 120；Windows 上无效
--upgrade-flow	兼容性模式：check 报告问题并失败；safe 在内存中应用安全升级
--verbose、-v	显示诊断输出与执行细节
--workers、-w	Worker 进程数；配合 --flow-dir 实现多 Worker Flow 共享。默认 1

使用 lfx run 运行 Flow

lfx run 从 JSON 文件运行 Flow 而不启动服务器，结果输出到 stdout。输入形态支持：JSON 文件路径、--input-value 内联值、stdin；不需要 Langflow API Key。

第 1 步：在同一终端导出变量（示例 Flow 需要 OpenAI Key）：

export OPENAI_API_KEY="sk-..."

第 2 步：依赖安装方式与 lfx serve 相同（Langflow 环境已齐备；独立 lfx/uvx 需按 lfx run 报错提示手动安装，Simple Agent 的依赖列表同上）。

第 3 步：运行：

uv run lfx run simple-agent-flow.json "Hello world"
# 或等价的
uv run lfx run simple-agent-flow.json --input-value "Hello world"

该 Flow 期望 Message 输入（普通文本字符串）。使用 --stdin 或 --flow-json 时，位置参数被让位给 Flow 定义，因此 --input-value 变为必填。

从 stdin 运行

--stdin 适合动态来源（API、数据库）或执行前动态修改 Flow。--input-value 必填：

# 从 stdin 读取 Flow JSON
cat simple-agent-flow.json | uv run lfx run --stdin \
  --input-value "Hello world" \
  --format json | jq '.result'

# 从远程 API 拉取后直接运行
curl https://api.example.com/flows/my-agent-flow | uv run lfx run --stdin \
  --input-value "Hello world"

# 执行前用 jq 修改 Flow（如把模型改成 gpt-4o）
cat simple-agent-flow.json | jq '(.data.nodes[] | select(.data.node.template.model_name.value) | .data.node.template.model_name.value) = "gpt-4o"' | \
  uv run lfx run --stdin \
  --input-value "Hello world" \
  --format json | jq '.result'

内联 JSON 运行

uv run lfx run --flow-json '{"data": {"nodes": [...], "edges": [...]}}' \
  --input-value "Hello world"

lfx run 选项表

选项	说明
--check-variables / --no-check-variables	校验 Flow 的全局变量。默认校验
--flow-json	以内联字符串传入 Flow JSON
--format、-f	输出格式：json/text/message/result，默认 json
--input-value	传入图执行的输入值
--session-id	会话 ID，Agent 与 Memory 组件据此跨运行维护历史；未设置时自动生成
--stdin	从 stdin 读取 Flow JSON
--timing	在输出中包含详细计时信息
--upgrade-flow	兼容性模式：check 报告并失败；safe 在运行前于内存中应用安全升级
--verbose、-v	基本进度与诊断输出
-vv	详细进度与调试信息
-vvv	完整调试输出（含组件日志）

用 Python 脚本编程式定义 Flow

除 JSON 外，lfx run 支持以 Python 脚本定义 Flow，无需可视化编辑器。完整示例——创建 simple_agent.py：

"""A simple agent flow example for Langflow.

Usage:
    uv run lfx run simple_agent.py "How are you?"
"""

import os
from pathlib import Path

from lfx import components as cp
from lfx.graph import Graph
from lfx.log.logger import LogConfig


async def get_graph() -> Graph:
    """Create and return the graph with async component initialization."""
    log_config = LogConfig(
        log_level="INFO",
        log_file=Path("langflow.log"),
    )

    chat_input = cp.ChatInput()
    agent = cp.AgentComponent()
    url_component = cp.URLComponent()
    tools = await url_component.to_toolkit()

    agent.set(
        model_name="gpt-4.1-mini",
        agent_llm="OpenAI",
        api_key=os.getenv("OPENAI_API_KEY"),
        input_value=chat_input.message_response,
        tools=tools,
    )
    chat_output = cp.ChatOutput().set(input_value=agent.message_response)

    return Graph(chat_input, chat_output, log_config=log_config)

安装依赖并设置 OPENAI_API_KEY 后运行：

uv run lfx run simple_agent.py "How are you?" --verbose

lfx run 的 Human-in-the-loop

当 Flow 含暂停节点（如 Human Input）且终端可交互时，lfx run 会在每个决策点自动暂停、在终端提示，然后沿所选分支继续；可用 --human-input / --no-human-input 强制指定行为。CLI 的 HITL 仅限交互式会话：

• 检查点保存在内存中——暂停期间进程退出即丢失运行；
• 没有持久化恢复：暂停的运行无法事后从其他终端或重启后恢复（没有 --resume <id>）；
• 非交互式运行（管道 stdin、CI 或 --no-human-input）不会暂停：暂停节点被直接穿透，运行继续，且 CLI 会打印警告，避免静默通过。

需要跨重启的持久暂停/恢复，应改用 Langflow 服务器的 v2 workflows API 运行 Flow。

lfx-mcp：把 Langflow 暴露给 MCP 客户端

lfx-mcp 是随 lfx 一起安装的独立可执行入口（pyproject.toml 中注册为 lfx-mcp = "lfx.mcp.__main__:main"）。它启动一个 MCP Server，让任何 MCP 兼容客户端都能以编程方式构建 Flow、管理组件、触发执行，从而操控一个运行中的 Langflow 实例。详细用法见 LFX_MCP.md：它通过 stdio 运行（MCP 客户端将其作为子进程拉起，无 HTTP 端口），需要环境变量 LANGFLOW_SERVER_URL（默认 http://localhost:7860）与 LANGFLOW_API_KEY；Flow 数据在服务端从不缓存，每个变更类工具都执行 GET → 修改 → PATCH 周期，组件注册表则在会话内首次访问时缓存。

开发工作流

在仓库 src/lfx 目录下：

make dev      # 安装开发依赖
make test     # 运行测试
make format   # 格式化代码

可插拔服务架构

LFX 支持可插拔服务架构，允许替换内置服务（存储、遥测、追踪等）为自己的实现，或复用 Langflow 的完整服务。详见 PLUGGABLE_SERVICES.md，要点：

• 三种发现机制：装饰器注册（导入时自注册，适合库）、配置文件显式映射（适合 CLI）、Python 包 entry points（适合可分发插件）；
• 发现顺序（后者覆盖前者）：entry points（最低）→ 装饰器注册 → 配置文件（最高）；
• 适配器注册表（Adapter Registries）：与「每类型一个实现」的 Service 不同，同一注册表内可按字符串键存放多个可互换适配器（如 deployment 下的 local/remote），通过 lfx.services.deps 的类型化访问器（如 get_deployment_adapter("local")）获取，惰性创建并缓存为单例；
• 配置可写在 lfx.toml（两文件共存时优先）或 pyproject.toml 的 [tool.lfx.*] 段。

扁平化组件访问

LFX 支持简化的组件导入方式，构建 Python Flow 时体验更好，且完全向后兼容传统导入：

旧风格：

from lfx.components.agents.agent import AgentComponent
from lfx.components.data.url import URLComponent
from lfx.components.input_output import ChatInput, ChatOutput

扁平风格：

from lfx import components as cp

chat_input = cp.ChatInput()
agent = cp.AgentComponent()
url_component = cp.URLComponent()
chat_output = cp.ChatOutput()

从 src/lfx/src/lfx/components/init.py 的源码结构看，lfx.components 包在导入时把各子模块组件（如 agents.agent、data.url）挂到包级命名空间下，实现 cp.ComponentName 的直接访问。

组件分类白名单与黑名单

加载 Flow 时可通过环境变量限制可用的组件分类。两个变量均可选，未设置或为空时加载组件索引中的全部分类：

变量	说明
LANGFLOW_COMPONENT_CATEGORY_ALLOWLIST	逗号分隔的包含分类列表。空（默认）则包含全部分类；设置后仅所列分类可用
LANGFLOW_COMPONENT_CATEGORY_BLOCKLIST	逗号分隔的排除分类列表。空（默认）则不排除；在 allowlist 之后生效

分类名不区分大小写；分类名与组件索引对齐（即 lfx.components 下的顶层目录），供应商分类（openai、anthropic、google、langchain_utilities 等）同样有效，完整集合取决于 LFX 版本与索引。allowlist/blocklist 中的虚拟关键字 core 会展开为与前端侧边栏对齐的一组核心分类：input_output、data_source、models_and_agents、llm_operations、files_and_knowledge、processing、flow_controls、utilities、prototypes、tools、agents、data、logic、helpers、models、vectorstores、inputs、outputs、prompts、chains、documentloaders、link_extractors、output_parsers、retrievers、textsplitters、toolkits。

用法示例：

# 仅白名单
export LANGFLOW_COMPONENT_CATEGORY_ALLOWLIST="openai,anthropic,google,processing,input_output"
uv run lfx serve my_flow.json

# 仅黑名单
export LANGFLOW_COMPONENT_CATEGORY_BLOCKLIST="prototypes,langchain_utilities"
uv run lfx run my_flow.json "Hello"

# 虚拟 core 关键字
export LANGFLOW_COMPONENT_CATEGORY_ALLOWLIST="core"
uv run lfx serve my_flow.json

过滤在组件索引加载时生效，需在运行 lfx serve/lfx run 之前设置环境变量。

小结：适用场景与限制

• 适用：把 Flow JSON 变成无 UI、无数据库的 API 端点；CI 中无头执行 Flow 并断言 --format json 输出；按请求隔离凭证的多租户部署；通过 lfx-mcp 让 Agent 客户端操控 Langflow 实例。
• 限制：所有依赖 langflow.db 的有状态操作（保存 Flow、消息存储、用户管理）不持久化；CLI 端 HITL 无持久恢复；多 Worker + --flow-dir 不支持 .py 脚本 Flow；Windows 上 gunicorn 系参数（--max-requests/--timeout/sync workers）不生效。

LFX 采用 MIT 许可证，详见 LICENSE。