Langflow 扩展包 lfx-amazon：接入 Amazon Bedrock 模型与 S3 上传的完整实践

本文以 Langflow 官方扩展包 lfx-amazon 为主体，介绍如何将 Amazon 系列组件（Bedrock 文本生成、Bedrock 向量化、S3 文件上传）作为独立扩展 Bundle 安装到 Langflow 中，包括组件注册机制、各组件的输入参数与底层实现原理、开发调试方式，以及旧版组件引用如何自动迁移到新的命名空间 ID。读完后你将能够独立完成该扩展包的安装、配置与开发验证，并理解 Langflow 扩展 Bundle 的目录约定与迁移机制。

扩展包定位与安装方式

lfx-amazon 是将 Amazon 相关组件从 Langflow 核心代码中剥离出来的独立扩展包，对应包元数据定义在 pyproject.toml 中：包名 lfx-amazon，当前版本 0.1.2，要求 Python >=3.10,<3.15，构建后端为 hatchling。它包含三类能力：

1. Amazon Bedrock 文本生成（传统 ChatBedrock API，已标记弃用）；
2. Amazon Bedrock Converse 文本生成（现代 Converse API，推荐）；
3. Amazon Bedrock 向量化（Embeddings） 与 S3 桶文件上传。

安装命令（来自 README）：

pip install lfx-amazon

运行时依赖

Bundle 的第三方依赖在 pyproject.toml 中明确声明，安装时会自动带入：

依赖	版本约束	作用
lfx	>=1.12.0.dev0,<2.0.0	提供 BUNDLE_API 组件开发接口，版本下限与 src/lfx/pyproject.toml 同步，通过 scripts/ci/sync_bundle_lfx_pin.py 在 make patch 时重新对齐
boto3	>=1.34.162,<2.0.0	AWS SDK，用于创建 bedrock-runtime 客户端与 S3 客户端
langchain-aws	>=1.4.1,<2.0.0	提供 ChatBedrock、ChatBedrockConverse、BedrockEmbeddings 等 LangChain 兼容封装

自动注册机制

该 Bundle 通过 Python entry-point 被发现。pyproject.toml 中声明了：

[project.entry-points."langflow.extensions"]
lfx-amazon = "lfx_amazon"

安装后重启 Langflow 服务，组件会出现在组件面板（palette）的 amazon 分组下，并使用带命名空间、带来源后缀的 ID，例如 ext:amazon:AmazonBedrockConverseComponent@official。这种 ext:<bundle>:<class>@<source> 格式的 ID 是 Langflow 扩展体系区分“核心组件”与“扩展组件”的关键：即使扩展组件的类名与旧版核心组件相同，也不会产生冲突。

组件清单本身由 extension.json 描述：

{
  "id": "lfx-amazon",
  "version": "0.1.2",
  "name": "Amazon",
  "lfx": { "compat": ["1"] },
  "bundles": [
    { "name": "amazon", "path": "components/amazon" }
  ]
}

从这份清单可以看出两个细节：

• lfx.compat: ["1"] 声明了对 BUNDLE_API 版本 1 的兼容，加载器会据此校验；
• bundles[0].path 为 components/amazon，它是相对于 manifest 所在目录（即 src/lfx_amazon/）解析的，实际指向 src/bundles/amazon/src/lfx_amazon/components/amazon。

wheel 构建时，hatch 配置（pyproject.toml）特意将 extension.json 与 components/**/*.py 打包进 lfx_amazon 包内，使得 importlib.metadata.files(dist) 能定位到 manifest，loader 才能正确解析 bundles[].path。

组件目录结构与懒加载

Bundle 内的四个组件类分别位于独立模块中：

文件	组件类	面板显示名
amazon_bedrock_model.py	AmazonBedrockComponent	Amazon Bedrock（legacy）
amazon_bedrock_converse.py	AmazonBedrockConverseComponent	Amazon Bedrock Converse（beta）
amazon_bedrock_embedding.py	AmazonBedrockEmbeddingsComponent	Amazon Bedrock Embeddings
s3_bucket_uploader.py	S3BucketUploaderComponent	S3 Bucket Uploader

components/amazon/__init__.py 采用懒导出（lazy re-export）模式：模块级不直接 import 组件类，而是通过 _dynamic_imports 映射表配合 __getattr__ 在首次访问时才加载对应模块。这样做的意义在于两点：

1. 保持与提取前 lfx.components.amazon.<Class> 的模块级类路径语义一致，便于旧 Flow 通过迁移表继续解析；
2. 避免 bundle 加载阶段就触发 langchain_aws、boto3 等重依赖的导入，加快启动并隔离缺失依赖的错误时机。

Amazon Bedrock 模型组件详解

Amazon Bedrock Converse（推荐）

amazon_bedrock_converse.py 中的 AmazonBedrockConverseComponent 基于 LangChain 的 ChatBedrockConverse（来自 langchain_aws.chat_models.bedrock_converse），使用 Bedrock 现代 Converse API，标记为 beta = True。

核心输入参数：

参数	类型	默认值	说明
model_id	Dropdown	anthropic.claude-3-5-sonnet-20241022-v2:0	模型 ID，选项来自 aws_constants.py 中的 AWS_MODEL_IDs，涵盖 Titan 系列、Claude 3.x/4.x 等（均标注 tool_calling=True）
aws_access_key_id	SecretStr	读环境变量 AWS_ACCESS_KEY_ID	AWS 访问密钥，必填
aws_secret_access_key	SecretStr	读环境变量 AWS_SECRET_ACCESS_KEY	AWS 秘密密钥，必填
aws_session_token	SecretStr	-	临时凭证的会话令牌，load_from_db=False 表示不持久化到数据库
credentials_profile_name	SecretStr	-	~/.aws/credentials 中的 profile 名，未提供则用 default profile
region_name	Dropdown	us-east-1	选项来自 AWS_REGIONS
endpoint_url	MessageTextInput	-	高级参数，自定义 Bedrock 端点
temperature	Float	0.7	高级参数，控制输出随机性
max_tokens	Int	4096	最大生成 token 数
top_p	Float	0.9	核采样参数
top_k	Int	250	限制候选词表大小；注意并非所有模型都支持，源码注释明确提示可通过 additional_model_fields 手动配置
disable_streaming	Bool	False	为 True 时关闭流式响应，适合批处理
additional_model_fields	Dict（list）	-	模型特定参数的逃生舱口

构建逻辑（build_model）值得注意的细节：

• 组件并不自己拼 boto3 会话，而是把凭证参数直接透传给 ChatBedrockConverse(**init_params)，由 langchain-aws 内部完成会话与客户端创建（见 amazon_bedrock_converse.py）；
• temperature、max_tokens、top_p 只有非 None 时才写入 init_params，避免覆盖 SDK 默认行为；
• 对 additional_model_fields，源码刻意不自动为 top_k 拼装 inferenceConfig，注释说明原因是部分模型会因此产生校验错误——用户需要按模型能力自行在 additional_model_fields 中给出；
• 异常处理具有引导性：捕获到 “validation error” 或 “converse api” 字样时，错误信息会提示“该模型可能不支持 Converse API，可改用 legacy 的 Amazon Bedrock 组件”（见 amazon_bedrock_converse.py），这与 legacy 组件形成兜底关系。

Amazon Bedrock（Legacy，已弃用）

amazon_bedrock_model.py 中的 AmazonBedrockComponent 基于 langchain_aws.ChatBedrock，类属性中显式声明了弃用信息：

legacy = True
replacement = "amazon.AmazonBedrockConverseModel"

这意味着 Langflow 会在界面上把它标记为遗留组件，并把 Amazon Bedrock Converse 组件作为替代推荐。其输入参数与 Converse 版基本同构（模型 ID 默认 anthropic.claude-3-haiku-20240307-v1:0），另有一个 model_kwargs DictInput 用于透传模型关键字参数。

与 Converse 版在底层实现上的关键差异在于凭证处理路径：legacy 版自己构建 boto3.Session 并创建 bedrock-runtime 客户端，再注入 ChatBedrock（见 amazon_bedrock_model.py）：

if self.aws_access_key_id or self.aws_secret_access_key:
    session = boto3.Session(
        aws_access_key_id=self.aws_access_key_id,
        aws_secret_access_key=self.aws_secret_access_key,
        aws_session_token=self.aws_session_token,
    )
elif self.credentials_profile_name:
    session = boto3.Session(profile_name=self.credentials_profile_name)
else:
    session = boto3.Session()
...
boto3_client = session.client("bedrock-runtime", **client_params)

这一“显式 Key → 凭证 profile → 默认会话”的三级回退逻辑，是本 bundle 中 AWS 组件的通用凭证模式，选型建议是：

• 日常开发优先用环境变量（AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY）——两个 Bedrock 文本组件的 SecretStr 输入默认值就是指向这两个环境变量的名字，且 load_from_db=False 避免真实密钥落库；
• 多账号/多环境场景用 credentials_profile_name 指定 ~/.aws/credentials 中的 profile；
• 需要自建网关或本地模拟（如 LocalStack 一类）时用 endpoint_url 覆盖端点。

Amazon Bedrock Embeddings

amazon_bedrock_embedding.py 中的 AmazonBedrockEmbeddingsComponent 负责把文本转为向量，供 RAG 流程使用。要点：

• 模型 ID 选项来自 AWS_EMBEDDING_MODEL_IDS，默认 amazon.titan-embed-text-v1；
• 输出为单个 Embeddings 类型的 Output（build_embeddings 方法），可直接接入 Langflow 中的向量存储类组件；
• 凭证与客户端构建逻辑与 legacy Bedrock 组件完全同构：同样是“显式 Key / profile / 默认会话”的三级回退，最终生成 bedrock-runtime 客户端并注入 langchain_aws.BedrockEmbeddings（见 amazon_bedrock_embedding.py）。

S3 Bucket Uploader

S3BucketUploaderComponent 是一个文件上传工具组件（直接继承 lfx 的 Component 基类），用于把上游组件产出的文件写入 S3 桶。输入参数：

参数	说明
aws_access_key_id / aws_secret_access_key	必填的 AWS 凭证（password=True，界面以密码形式呈现）
bucket_name	目标桶名
strategy	上传策略：Store Data 或 Store Original File
data_inputs	HandleInput（list，必填），接收 Data、JSON 类型输入，通常接文件类/目录类组件
s3_prefix	高级参数，所有上传 Key 的前缀
strip_path	高级参数，True 时只保留文件名、去掉路径

两条策略对应两个内部方法，由 process_files 的策略分发表调度（s3_bucket_uploader.py）：

• Store Data（process_files_by_data）：遍历每个 data_inputs，取 file_path 与 text 两个字段，两者都存在时才调用 put_object 上传解析后的文本内容——即把源文件“解析并存储为 LangFlow 数据”；
• Store Original File（process_files_by_name）：只要 file_path 存在，就调用 upload_file 上传原始文件本身。

Key 的生成由 _normalize_path 完成：先按 strip_path 决定是否只保留 Path(file_path).name，再与 s3_prefix 用 Path(prefix) / processed_path 拼接。S3 客户端由 _s3_client 用传入的显式 Access Key 构建，注意该组件与三个 Bedrock 组件不同——它只支持显式密钥方式，没有环境变量默认值。

开发模式与验证命令

按照 README 的 Develop 一节，本地开发流程为：

cd src/bundles/amazon
pip install -e .
lfx extension validate src/lfx_amazon

• pip install -e . 以可编辑模式安装；entry-point 注释（pyproject.toml）说明：manifest 分发包通过 langflow.extensions entry-point 被发现，而可编辑安装若 dist.files 只暴露 dist-info 条目，同样回退到该 entry-point 来定位 manifest——因此可编辑安装也能被加载器识别；
• lfx extension validate src/lfx_amazon 校验 manifest 及其组件，参数指向 manifest 所在包目录，用于在发布前捕获 manifest 结构或组件定义问题。

旧 Flow 的迁移机制

对于已经保存过引用旧组件的 Flow，README 的 Migration 一节说明：保存的 Flow 中引用旧类名或 lfx.components.amazon.* 旧导入路径的节点，会被 migration_table.json 中的迁移表自动重写为新的命名空间 ID。该表中 Amazon 相关条目（added_in: "1.11.0"）确认了三类映射：

• 裸类名（bare class name），如 AmazonBedrockConverseComponent → ext:amazon:AmazonBedrockConverseComponent@official；
• 模块级与文件级旧导入路径，如 lfx.components.amazon.AmazonBedrockEmbeddingsComponent 与 lfx.components.amazon.amazon_bedrock_embedding.AmazonBedrockEmbeddingsComponent → ext:amazon:AmazonBedrockEmbeddingsComponent@official；
• 旧遗留槽位（legacy slot），如 ext:amazon:AmazonBedrockComponent@official-pre-a → ext:amazon:AmazonBedrockComponent@official。

这与 components/amazon/__init__.py 的模块 docstring 相互印证：懒导出层“镜像提取前的 lfx.components.amazon 布局”，保证旧 Flow 在重写后仍能解析到模块级类。迁移覆盖的四个组件正是本文前述的全部四个类，且均标注 added_in: "1.11.0"，即该迁移表自 Langflow 1.11.0 起生效。

小结与适用前提

lfx-amazon 展示了一个典型的 Langflow 官方扩展 Bundle 形态：独立 pyproject.toml 声明依赖与 entry-point，extension.json 描述 manifest 与 bundle 路径，组件代码统一放在 bundles[].path 指向的目录中，历史引用交给迁移表处理。使用时需要注意：

• 安装后必须重启 Langflow 服务组件才出现在面板中；
• Bedrock 组件要求账户侧已开通对应模型的 Bedrock 访问权限，且 model_id 必须与所在 region_name 中实际可用的模型匹配；
• 新流程推荐选用 Amazon Bedrock Converse 组件；遇到 Converse API 兼容性问题时按报错提示回退到 legacy 组件，或用 additional_model_fields 微调模型参数；
• S3 Bucket Uploader 仅接受显式 Access Key 凭证，并依赖 data_inputs 上游提供 file_path（及 Store Data 策略下的 text）字段。