多模型路由：在画布上实现运行时模型切换

学习目标

• 掌握 Langflow 中模型组件的动态表单机制（real_time_refresh + update_build_config）
• 理解 LiteLLM 统一路由与专用 Provider 组件的选择策略
• 学会在画布中安全管理模型凭证（API Key、Base URL）

前置知识

本章涉及多模型适配的通用原理，建议先阅读：

• 多模型适配架构
• 可视化画布中的模型路由与动态切换

下文假设你已理解多模型路由的基本概念，直接聚焦 Langflow 的具体实现。

---

项目实践

1. 动态表单：real_time_refresh 实战

Langflow 的 OpenAI 组件通过 real_time_refresh 实现模型选择时动态切换可用参数：

class OpenAIChatModel(LCModelComponent):
    inputs = [
        Input(
            name="model_name",
            field_type="str",
            display_name="模型名称",
            real_time_refresh=True,  # 值变化时触发 update_build_config
            options=["gpt-4o", "gpt-4o-mini", "o1", "o3"],
        ),
        Input(
            name="temperature",
            field_type="float",
            display_name="Temperature",
            default=0.7,
        ),
        Input(
            name="api_key",
            field_type="str",
            display_name="API Key",
            password=True,  # 输入框显示为密码模式
        ),
    ]

    def update_build_config(self, build_config, field_value, field_name):
        if field_name == "model_name":
            # 根据选择的模型调整可用参数
            if field_value in ("o1", "o3"):
                # o1/o3 不支持 temperature，隐藏该字段
                build_config["temperature"]["hidden"] = True
            else:
                build_config["temperature"]["hidden"] = False
        return build_config

执行流程：

2. LiteLLM 统一路由 vs 专用 Provider

Langflow 同时提供两种模型接入方式：

LiteLLM 组件（src/lfx/src/lfx/components/litellm/）：

• 一个组件支持 100+ 模型 Provider
• 通过 model 输入字段选择模型（如 "openai/gpt-4o", "anthropic/claude-3-opus"）
• 仅暴露通用参数（model、api_key、temperature、max_tokens）
• 适合：快速原型、模型对比实验、不确定最终 Provider 的场景

专用 Provider 组件（openai/, anthropic/, ollama/, vllm/ 等目录）：

• 每个 Provider 独立组件，暴露该 Provider 的全部参数
• OpenAI 组件支持 response_format、seed、logprobs 等 OpenAI 特有参数
• Anthropic 组件支持 system_prompt、top_k、cache_control 等 Anthropic 特有参数
• 适合：生产环境、需要精细调参、使用 Provider 特有功能

画布中的选择策略：

3. 凭证管理：Variable 服务

Langflow 的模型凭证通过 Variable 服务管理，而非硬编码在组件配置中：

Input(
    name="api_key",
    field_type="str",
    display_name="API Key",
    password=True,
    load_from_db=True,  # 从 Variable 服务加载
)

凭证查找链：

安全特性：

• Variable 中的凭证在数据库中加密存储
• 导出 Flow JSON 时，凭证字段自动替换为 Variable 引用名，不泄露明文
• 环境变量优先级高于手动输入，便于 CI/CD 中自动注入

---

问题与规避

陷阱	现象	对策
模型切换后参数残留	切换到不支持 temperature 的模型后，旧值仍保存在配置中	在 update_build_config 中显式清除不相关字段的 value
凭证泄露到 Flow JSON	直接手动输入 API Key 后导出 Flow	使用 Variable 引用，导出时自动脱敏
LiteLLM 隐藏关键参数	需要 OpenAI 的 response_format 但 LiteLLM 不暴露	切换到专用 OpenAI 组件
环境变量未生效	设置了 LANGFLOW_OPENAI_API_KEY 但组件仍提示缺少 Key	确保 Langflow 进程重启后环境变量才生效

---

设计取舍

为什么选择前端触发的动态表单而非后端全量下发：

• 前端触发：仅传输变更的字段，网络开销小；但需要维护字段间的依赖逻辑
• 后端全量下发：每次模型选择都重新下发完整表单配置；网络开销大但实现简单

Langflow 选择前端触发方案，因为画布上的组件通常有 10-20 个输入字段，全量下放在弱网环境下体验差。

---

参考来源

• 源码：src/lfx/src/lfx/components/openai/openai_chat_model.py
• 源码：src/lfx/src/lfx/components/litellm/
• 源码：src/backend/base/langflow/services/database/models/variable.py