Langflow Cohere 扩展 Bundle 详解：lfx-cohere 的安装、组件参数与旧工作流迁移机制

lfx-cohere 是 Langflow 将 Cohere 系列组件（大语言模型、向量嵌入、文档重排序）从核心包拆分出来的独立扩展 Bundle。本文基于 src/bundles/cohere/README.md 展开，结合包内清单、组件源码与迁移表，说明该 Bundle 的安装注册机制、三个组件的完整参数与实现细节，以及旧版已保存工作流如何被自动改写为新命名空间 ID。

一、Bundle 结构：一份清单与一组组件

lfx-cohere 遵循 Langflow 扩展 Bundle 的标准布局：一份 extension.json 清单加上一组组件模块。

清单文件 extension.json 声明了 Bundle 的核心元数据：

{
  "$schema": "https://schemas.langflow.org/extension/v1.json",
  "id": "lfx-cohere",
  "version": "0.1.1",
  "name": "Cohere",
  "description": "Cohere component(s) as a standalone Langflow Extension Bundle.",
  "lfx": {
    "compat": ["1"]
  },
  "bundles": [
    {
      "name": "cohere",
      "path": "components/cohere"
    }
  ]
}

几个关键字段：

• id / version：Bundle 的唯一标识与版本，当前版本为 0.1.1；
• lfx.compat: ["1"]：声明该 Bundle 兼容的 BUNDLE_API 主版本线，加载器会据此校验 API 兼容性；
• bundles[].path：相对清单所在目录的组件目录路径，即 src/bundles/cohere/src/lfx_cohere/components/cohere，其中包含三个组件模块：

组件类	模块	命名空间 ID
CohereComponent	cohere_models.py	ext:cohere:CohereComponent@official
CohereEmbeddingsComponent	cohere_embeddings.py	ext:cohere:CohereEmbeddingsComponent@official
CohereRerankComponent	cohere_rerank.py	ext:cohere:CohereRerankComponent@official

组件包的 init.py 采用惰性重导出：通过 _dynamic_imports 映射表与模块级 __getattr__，只在真正访问 CohereComponent 等符号时才去导入对应子模块。源码注释说明这是为了对齐拆分前 lfx.components.cohere 的布局，保证旧工作流引用的模块级类在迁移改写后仍能正常解析。

二、安装与自动注册

安装命令（见 README）：

pip install lfx-cohere

注册机制的关键在于 pyproject.toml 中的 entry-point 声明：

[project.entry-points."langflow.extensions"]
lfx-cohere = "lfx_cohere"

Langflow 服务端启动时会通过 langflow.extensions 这一 entry-point 自动发现已安装的扩展分布（distribution），读取其 extension.json 清单并加载组件。正如 README 所述：安装后重启 Langflow 服务，组件就会以命名空间 ID ext:cohere:<Class>@official 出现在调色板（palette）的 cohere 分组下。

从构建配置看，extension.json 与组件源码都被打包进 lfx_cohere 包内：

[tool.hatch.build.targets.wheel]
packages = ["src/lfx_cohere"]
include = [
    "src/lfx_cohere/extension.json",
    "src/lfx_cohere/components/**/*.py",
]

这样 importlib.metadata.files(dist) 才能找到清单，加载器再把 bundles[].path 解析为相对清单目录的路径。

运行时依赖约束

pyproject.toml 中声明了该 Bundle 的依赖：

requires-python = ">=3.10,<3.15"
dependencies = [
    "lfx>=1.12.0.dev0,<2.0.0",
    "langchain-cohere~=0.5.0",
]

• lfx 的下界锚定在当前 major.minor 线、上界卡在下一个大版本之下；文件内注释说明该下界在拆分时从 src/lfx/pyproject.toml 读取，并会通过 make patch 流程由 scripts/ci/sync_bundle_lfx_pin.py 重新同步；
• 组件实际调用 Cohere 能力依赖 langchain-cohere（约 0.5 版）提供的 ChatCohere、CohereEmbeddings、CohereRerank 封装；
• 细粒度的 BUNDLE_API 兼容性则依靠清单中 lfx.compat 与 BUNDLE_API_VERSION 的比对来强制执行。

三、开发验证流程

README 给出的开发流程为：

cd src/bundles/cohere
pip install -e .
lfx extension validate src/lfx_cohere

• pip install -e . 以可编辑方式安装本 Bundle，方便在 components/cohere 下直接改动组件代码并即时生效；
• lfx extension validate 对清单目录做静态校验（清单结构、组件声明合法性等），是在发布前确认 Bundle 可被加载的第一道检查。

pyproject 中的注释还提到一个细节：可编辑安装若其 dist.files 只暴露 dist-info 条目，加载器会回退到 entry-point 来定位清单——这正是上面 langflow.extensions entry-point 同时存在的意义。

四、组件详解

4.1 Cohere Language Models（CohereModel）

CohereComponent 继承 LCModelComponent，用于把 Cohere 大语言模型接入工作流中的 LLM 插槽。组件参数：

参数	类型	说明
（基础输入）	LCModelComponent.get_base_inputs()	继承自通用 LLM 组件基类的公共参数
cohere_api_key	SecretStrInput	Cohere API Key，必填（required=True），默认值为环境变量名 COHERE_API_KEY
temperature	SliderInput	采样温度，范围 0–2、步长 0.01，默认 0.75；值越小输出越确定，越大越发散

核心构建逻辑：

def build_model(self) -> LanguageModel:
    cohere_api_key = self.cohere_api_key
    temperature = self.temperature
    api_key = SecretStr(cohere_api_key).get_secret_value() if cohere_api_key else None
    return ChatCohere(
        temperature=temperature or 0.75,
        cohere_api_key=api_key,
    )

从源码结构看，密钥先经过 SecretStr 解包再以 cohere_api_key 传入 ChatCohere，temperature 缺省时回退到 0.75。display_name 为 "Cohere Language Models"，图标为 Cohere。

4.2 Cohere Embeddings（CohereEmbeddings）

CohereEmbeddingsComponent 用于生成文本向量，输出单个 Embeddings 类型的 embeddings 输出（构建方法 build_embeddings）。完整参数表：

参数	类型	默认值 / 取值	说明
api_key	SecretStrInput	必填，real_time_refresh=True	Cohere API Key；变更后触发实时刷新
model_name	DropdownInput	默认 embed-english-v2.0；选项含 embed-multilingual-v2.0、embed-english-light-v2.0、embed-multilingual-light-v2.0	嵌入模型；combobox=True 允许手动输入模型名
truncate	MessageTextInput	高级项	输入超长时的截断策略
max_retries	IntInput	3	请求失败重试次数
user_agent	MessageTextInput	langchain	请求 User-Agent 标识
request_timeout	FloatInput	空	请求超时（秒），空则不设置

构建时参数被整体透传给 langchain_cohere.CohereEmbeddings；若构造失败（通常是 API Key 或模型参数无效），会抛出带提示的 ValueError："Please verify the API key and model parameters, and try again."

该组件还有两处值得注意的动态行为：

1. 模型列表拉取：get_model() 使用 cohere.ClientV2(api_key) 调用 models.list(endpoint="embed")，返回当前账号可用的嵌入模型名列表；
2. 选项联动刷新：update_build_config 钩子在 api_key 或 model_name 字段变化时，若已填写 API Key，则用 get_model() 的结果刷新下拉框选项；未填 Key 时则直接采用传入的字段值。因此在前端编辑表单时，填入密钥后模型下拉列表会自动更新为实时可用列表。

4.3 Cohere Rerank（CohereRerank）

CohereRerankComponent 继承 LCCompressorComponent，作为文档压缩器接入 RAG 检索链路，输出 reranked_documents（方法 compress_documents）。

参数包括继承自压缩器基类的通用输入（其中 top_n 在 src/lfx/src/lfx/base/compressors/model.py 中定义为 IntInput、默认 3 的高级项），加上本组件特有的两个字段：

参数	类型	默认值 / 取值	说明
api_key	SecretStrInput	—	Cohere API Key
model	DropdownInput	默认 rerank-english-v3.0；选项含 rerank-multilingual-v3.0、rerank-english-v2.0、rerank-multilingual-v2.0	重排序模型

build_compressor 在运行期才延迟导入 CohereRerank（from langchain_cohere import CohereRerank），未安装 langchain-cohere 时抛出带安装提示的 ImportError；正常路径上以 cohere_api_key、model、top_n 三个参数构造实例。

五、旧工作流迁移：从 lfx.components.cohere.* 到命名空间 ID

README 的 Migration 一节指出：引用旧类名或 lfx.components.cohere.* 旧导入路径的已保存工作流，会被迁移表自动改写为新的命名空间 ID。迁移表位于 src/lfx/src/lfx/extension/migration/migration_table.json，其中每个组件覆盖四种旧形态（均标注 added_in: 1.11.0）：

1. 裸类名："bare_class_name": "CohereComponent" → ext:cohere:CohereComponent@official；
2. 完整旧导入路径："import_path": "lfx.components.cohere.cohere_models.CohereComponent"；
3. 包级重导出路径："import_path": "lfx.components.cohere.CohereComponent"；
4. Phase-A 之前的槽位："legacy_slot": "ext:cohere:CohereComponent@official-pre-a"。

三个组件 × 四种形态，共 12 条迁移记录，目标统一为 ext:cohere:<Class>@official。

配套的旧路径兼容 shim 在 src/lfx/src/lfx/components/cohere/init.py：它不含任何组件实现，仅把 lfx.components.cohere 重新指向已安装的 lfx_cohere.components.cohere 分布；若未安装 lfx-cohere，则抛出带 pip install lfx-cohere 安装提示的 ModuleNotFoundError。源码注释说明该 shim 将在弃用窗口结束（M4）时移除。

这一迁移链路由集成测试 src/lfx/tests/integration/extension/test_pilot_cohere_upgrade.py 覆盖：测试对三个组件类逐一构造模拟的已保存工作流节点，调用 migrate_flow_payload 断言裸类名、完整导入路径、包级重导出路径、pre-Phase-A 槽位四种形态都被改写为 ext:cohere:<Class>@official，并额外验证分布可导入性与清单可发现性。

六、小结与适用前提

• 适用版本：迁移记录标注 added_in: 1.11.0，lfx 依赖下界为 1.12.0.dev0，因此独立使用 lfx-cohere 需要较新的 lfx/Langflow 版本线；Python 要求 >=3.10,<3.15。
• 升级路径：从旧版 Langflow 升级时，无需手动改工作流 JSON——加载器会依据迁移表自动完成 ID 改写；lfx.components.cohere 旧导入路径由 shim 兜底一段时间。
• 验证与调试入口：开发态可用 lfx extension validate 校验清单；加载异常时可先确认 langflow.extensions entry-point 是否被 pip 正确注册、extension.json 是否随 wheel 打包。

相关源码路径索引：

• Bundle 文档：src/bundles/cohere/README.md
• 打包与依赖：src/bundles/cohere/pyproject.toml
• 清单：src/bundles/cohere/src/lfx_cohere/extension.json
• 组件实现：cohere_models.py、cohere_embeddings.py、cohere_rerank.py
• 迁移表与 shim：migration_table.json、components/cohere shim
• 升级回归测试：test_pilot_cohere_upgrade.py