通过 OpenAI Compatible 供应商把 Langflow 接到 Router One

Langflow 是开源的可视化 LLM 流程与 Agent 搭建工具：在画布上连接 Chat Input、Prompt Template、Language Model、Agent 和各类工具组件，然后在编辑器里运行，或通过 Langflow 自己的 API 调用。从 Langflow 1.11 起，模型接入统一在 Settings → Model Providers 里全局配置一次，列表里有一个 OpenAI Compatible 供应商：填 base URL 和 Key，它就从该端点的 /v1/models 发现模型。把它指向 Router One，所有 Language Model 和 Agent 字段都能用一把 Key 调 GPT、Claude、Gemini、Grok 和 DeepSeek 系列，每次请求在 Dashboard → Logs 都有成本 Trace。本指南按 Langflow 1.12.2 编写，讲清供应商该填什么、内置 OpenAI 组件这条备选路径、一次 Agent 运行会产生多少请求，以及 embeddings 为什么必须留在别的供应商。

为 Langflow 创建专用 Key

安装 Langflow 1.12，并为这个实例单独建 Key

OSS Python 包要求 Python 3.10 到 3.14 和 uv：用 uv pip install langflow 安装，uv run langflow run 启动，打开 http://127.0.0.1:7860。其他官方方式是 Langflow Desktop（macOS 13 及以上，或 Windows 安装包）和 langflowai/langflow Docker 镜像，镜像同样监听 7860。OpenAI Compatible 供应商随 langflow 包一起安装，不需要额外装东西；它最早出现在 1.11.0，而「base URL 缺 /v1 时自动补上」是 1.12.0 才有的，所以在 1.11.x 上要自己写 /v1。然后到 Dashboard → API Keys 为这个 Langflow 实例单独创建一把设了 maxSpend 的 Router One Key。容器或无界面服务器上，供应商可以从环境变量读取同样两个值，Key 不必经过界面：

docker run (Langflow + provider env)

docker run -p 7860:7860 \
  -e LANGFLOW_AUTO_LOGIN=false \
  -e LANGFLOW_SUPERUSER_PASSWORD=<strong-password> \
  -e OPENAI_COMPATIBLE_BASE_URL=https://api.router.one/v1 \
  -e OPENAI_COMPATIBLE_API_KEY=sk-your-router-one-key \
  langflowai/langflow:latest

把 Langflow 配置到 Router One base URL

点头像 → Settings → Model Providers，选 OpenAI Compatible。Base URL 填 https://api.router.one/v1：供应商用这个值作为 base_url 构造 LangChain 的 ChatOpenAI 客户端，客户端把请求发到 base URL 加 /chat/completions，所以 /v1 要写在这个字段里。API Key 填 Router One Key；Langflow 把它标为可选，只是因为本地服务可能不需要鉴权。点 Save：Langflow 会带着 Key（Bearer）请求 /v1/models 来验证这一对值，然后把发现的模型列在 Language Models 和 Embedding Models 下。在 Language Models 里启用要用的聊天模型，Embedding Models 下的全部保持关闭。在流程里添加 Language Model 组件（或 Agent），打开它的 Language Model 字段，选 OpenAI Compatible 和一个已发现的模型；显示的名称就是精确的目录模型 ID，含厂商前缀。这个供应商同一时间只能存一个端点，第二个网关或本地服务要用别的供应商条目：

langflow-model-provider

# Langflow 1.12 → profile icon → Settings → Model Providers → OpenAI Compatible
Base URL:  https://api.router.one/v1
API Key:   sk-your-router-one-key
# Save → Langflow probes /v1/models and lists the catalog
# Language Models:   enable the chat model IDs you use
# Embedding Models:  leave off (no /v1/embeddings on the gateway)

# In a flow: Language Model (or Agent) → Language Model field
Provider:  OpenAI Compatible
Model:     <exact-model-id-from-/models>

# Alternative: Bundles → OpenAI → OpenAI component (advanced controls)
OpenAI API Base:  https://api.router.one/v1
OpenAI API Key:   sk-your-router-one-key (Credential-type global variable)
Model Name:       type the exact ID, e.g. anthropic/claude-sonnet-5

Langflow 的哪个字段发出哪种请求

到达网关的路径有两条。全局的 OpenAI Compatible 供应商是主路径；内置的 OpenAI 组件是备选，适合想手动输入模型 ID、或要在同一实例里保留第二个端点的情况。两条路径发的都是 Chat Completions：

Langflow 字段	填什么	发出什么请求 / 怎么验证
Model Providers → OpenAI Compatible → Base URL	https://api.router.one/v1	保存时探测 GET /v1/models；对话请求发到 POST /v1/chat/completions。1.12 会自动补上缺少的 /v1，1.11.x 不会
Model Providers → OpenAI Compatible → API Key	为这个实例单独创建、设了 maxSpend 的 Router One Key	以 Authorization: Bearer 发送；探测返回 401 或 403 时保存失败并提示认证错误
Language Models 开关	只开你要用的聊天模型 ID	/v1/models 列出整个目录，生图和视频 ID 也会被发现；不要为 Language Model 字段启用它们
Embedding Models 开关	这个供应商下全部保持关闭	Langflow 会把每个发现的 ID 同时标成 embedding 模型；Router One 没有 /v1/embeddings
Language Model 组件 → Model Name Override（高级）	精确的目录模型 ID，或存着 ID 的全局变量	运行时覆盖所选模型；要求字段里是内置的模型选择，而不是连进来的模型对象
Agent → Language Model	OpenAI Compatible + 模型详情页列出工具调用的模型	该字段只列标记为支持工具调用的模型，而 Langflow 把发现的语言模型一律标成支持，所以要自己核对模型详情页
Agent → Max Iterations（高级）	默认 15	一次 Agent 运行最多可发起的模型调用次数；每次调用都是独立的请求和 Trace
OpenAI 组件 → OpenAI API Base（高级）	https://api.router.one/v1	备选路径：Model Name 是可输入文字的下拉框，可以直接填 anthropic/claude-sonnet-5 这样的 ID

备选路径：内置的 OpenAI 组件

Bundles → OpenAI → OpenAI 是一个独立的语言模型组件，自带连接字段，与全局供应商无关。打开它的高级设置，把 OpenAI API Base 填成 https://api.router.one/v1；OpenAI API Key 填 Router One Key，最好存成 Credential 类型的全局变量（Settings → Global Variables），这样值在编辑器里是打码的。Model Name 是下拉框：列表是固定的一组 OpenAI 名称，不会从网关拉取，但可以直接输入文字，所以把精确的目录 ID 粘进去即可。有三处默认值和全局路径不同，第一次运行前最好知道。Max Retries 默认 5，Timeout 默认 700 秒。Temperature 0.1 和 Seed 1 会随每次请求发送，因为组件只对自己推理模型列表里的名称去掉这两个参数，而且是对 gpt-5 这类不带前缀的名称做完全匹配；带厂商前缀的目录 ID 永远匹配不上。如果 400 错误点名了 temperature 或 seed，那是模型拒绝了这个参数：到 Dashboard → Logs 看完整消息和 request_id，改参数值，不要去改 base URL。要用这个组件驱动 Agent，把它的输出从 Model Response 切换成 Language Model，再连到 Agent 的 Language Model 端口。

给一个 Langflow 实例定预算，embeddings 留在别处

一次流程运行不等于一次请求。路径上的每个 Language Model 组件算一次请求，Agent 每拿到一次工具结果就再调一次模型，直到 Max Iterations 为止，失败的调用还会被底层的 OpenAI 客户端重试：全局供应商不传重试次数，用的是客户端默认的 2 次，而内置 OpenAI 组件要求 5 次。每一次真正到达网关的尝试，都是 Dashboard → Logs 里独立的一行，带模型、tokens、费用、延迟、状态和 request_id。给每个 Langflow 实例单独一把设了 maxSpend 的 Router One Key，循环的 Agent 或定时调用方会在上限处停下并返回 HTTP 402，钱包余额和其他 Key 不受影响。检索类流程还需要 embedding 模型，这部分不能走网关：Router One 在 /v1/chat/completions 上提供聊天模型，没有 embeddings 和 rerank 端点，所以 Embedding Model 组件要留在别的供应商或本地 embedding 模型上，只把语言模型指向 Router One。Langflow 自己的 API 又是另一回事：你 Langflow 服务器上的 POST /api/v1/run/<flow-id> 用来运行流程，用 x-api-key 头里的 Langflow API Key 鉴权。那把 Key 也以 sk- 开头，所以两把 Key 要标清楚；Langflow 的 Key 不会发给网关，Router One 的 Key 也不要填进 x-api-key。Langflow 的 MCP server 同理，它把流程暴露成工具，与网关的 /v1 路由无关。

Langflow 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 Langflow 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个工具单独建 API Key，并设置 maxSpend 消费上限。

Langflow 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

在 trace 里验证 Langflow 的调用

先在 Langflow 发出一次简单文本请求，再到 Dashboard → Logs 按时间、模型和 request_id 核对 trace：tokens、花费、延迟和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

常见问题

保存 OpenAI Compatible 供应商时失败，这些报错分别是什么意思？

Langflow 通过请求 /v1/models 来验证供应商，报错是几条固定消息之一。'Authentication failed for the OpenAI-compatible endpoint. Check OPENAI_COMPATIBLE_API_KEY.' 表示探测拿到 401 或 403：Key 填错、已被删除，或多了空格；网关侧无效 Key 对应 401 AUTH_INVALID_API_KEY。'The OpenAI-compatible endpoint at … returned HTTP 404 for …/models. Check that the base URL points to an OpenAI-compatible API.' 表示路径不对，常见的是写成了 /v1/v1 或末尾多了一段路径；消息里会打印它实际请求的 URL，和 https://api.router.one/v1/models 对比即可。'Could not connect to the OpenAI-compatible endpoint at …' 和 '… timed out.' 是运行 Langflow 的那台机器或容器的网络错误；探测只等 5 秒且不跟随重定向，检查那台主机的出站 HTTPS 和代理设置。如果保存成功但模型列表是空的，说明验证通过后模型发现静默失败：重新打开供应商再保存一次，然后查看 Langflow 服务端日志。

我要的模型不在 Language Model 下拉里，怎么用它的精确 ID？

先看开关：下拉只显示在 Settings → Model Providers → OpenAI Compatible → Language Models 里启用的模型，而 Langflow 只把发现的前五个 ID 标为默认。只要 ID 在目录里，它就在那个列表里，启用即可。如果想在运行时再指定模型，打开 Language Model 组件的高级设置，把 Model Name Override 填成精确的目录 ID，例如 anthropic/claude-sonnet-5，或绑定到一个全局变量。另一条路是内置的 OpenAI 组件，它的 Model Name 下拉框可以输入任意 ID。无论哪种方式，ID 都从 /models 页逐字复制，含前缀。

Embedding Model 组件或知识库能不能也用 Router One？

不能。/v1/models 不带能力信息，所以 Langflow 会把发现的每个 ID 都放进 Embedding Model 的选择列表，Router One 的聊天模型也会出现在那里；但选中后 Langflow 会去调 /v1/embeddings，而网关不提供这个端点。embeddings 留在别的供应商或本地模型上，Embedding Models 下的 OpenAI Compatible 条目保持关闭。一把 Router One Key 仍然覆盖这个实例里所有的 Language Model 和 Agent 组件。

Langflow 能通过网关用哪些模型？

选用当前目录中同时支持 Langflow 所用端点和所需功能的模型。精确 ID、当前单价与能力以 /models 及模型详情为准；不要仅按 GPT、Claude 等系列名判断兼容性。客户端能列出模型，只证明模型发现成功，仍需验证实际调用。

能列出模型，但调用报 400 或 404，怎么办？

先记录实际请求路径和错误消息，再核对精确模型 ID。400 可能是参数、工具类型或模型与端点不匹配；404 可能是请求路径或资源不存在，不能直接判定模型下线。若错误提示 must be called via，按它指明的端点调整客户端 provider，或换用支持当前端点的模型。不要在所有工具里统一增删 /v1 或 /chat/completions。

中国大陆能直连吗？

能。网关在大陆可直连、无需 VPN，配置与全球环境完全一致。

报 401/402/403/429 怎么排查？

先到 Dashboard → Logs 核对请求及错误消息。401 查 Key 是否传入和有效；402 查钱包余额与 maxSpend；403 查 Key 权限和访问限制；429 查请求频率、token 限额及上游限流，按错误来源处理。保留 request_id，再按错误码速查页逐项排查。

为 Langflow 创建专用 Key