如何安装和使用 FlashAlign 进行按需模型对齐

什么是 FlashAlign？

FlashAlign 是 Aevonix Research 开发的开源系统，可按需将对齐配置应用于受支持的语言模型。您可以按请求选择配置，也可以让配置持续作用于所有经过 FlashAlign 路由的请求。这些配置适用于受支持的基础权重和量化权重，且不会永久修改它们。

随附的 V1 入门配置主要用于减少拒答。FlashAlign 可以直接运行，也可以与 Hermes 或 OpenClaw 集成，或连接到自定义执行框架。托管推理需要 Linux 和 NVIDIA GPU。

FlashAlign 只会改变通过其配置的路由或网关 URL 发送的模型调用。您的执行框架仍负责决定谁可以发送消息以及哪些工具可以运行。

主要功能

• 按需配置：在推理引擎已加载的配置之间按请求切换。
• 可逆操作：应用配置时不会永久更改受支持的模型权重。
• 两种激活模式：在“已验证联系人”模式下将配置限制于已验证联系人，或使用“始终启用”模式将配置应用于所有路由请求。
• 工具继承控制：在“已验证联系人”模式下，选择哪些工具可以将活动配置传递给委托任务。
• 执行框架集成：将 FlashAlign 与 Hermes、OpenClaw、直接客户端或自定义执行框架配合使用。
• 消息适配器：内置适配器支持 WhatsApp 和 RCS 私信，并可选择启用 SMS 和 Telegram。
• 安装防护：安装程序会检测本地模型和执行框架，选择匹配的配置，检查激活状态，创建部署签名密钥，并备份发生更改的配置。
• 配置检查：在设置前查看配置的模型固定版本、算子、站点、秩和哈希值。

受支持的模型和引擎

FlashAlign 1.1.1 列出了五个入门模型配置及其引擎支持情况：

• DeepSeek V4.1 Flash 1017：vLLM 或 TensorFold。
• GLM 5.3 Full：TensorFold。
• GLM 5.3 Flash：TensorFold 或 SGLang。
• Qwen3.8-27B：TensorFold、vLLM、SGLang 或 llama.cpp。
• Gemma 4 26B A4B：TensorFold、vLLM、SGLang 或 llama.cpp。

仓库中包含四个紧凑型配置。DeepSeek 配置使用 1.09 GB 的原生张量载荷，安装程序会从公开发行版本下载该载荷并通过校验和进行验证。无需私有仓库或登录。

要求

安装 FlashAlign 前，请确认您的环境满足相关要求：

• 配备 NVIDIA GPU 的 Linux 推理主机。
• 用于安装和适配器的 Python 3.10 或更高版本。
• 使用 TensorFold 软件包时，CPU 和 GPU 架构必须匹配。
• 受支持的模型检查点及匹配的配置。
• 实现 FlashAlign 引擎契约的引擎。
• 对于 OpenAI 兼容客户端，需要支持 Chat Completions。
• 对于 OpenClaw，需要兼容的原生插件 API，以及 24.x 系列的 Node 24.22.1 或更高版本，或 26.x 系列的 Node 26.12.1 或更高版本。

有关硬件要求、固定检查点、引擎限制、频道和委托支持，请参阅项目的兼容性指南。

安装 FlashAlign

1. 下载受支持的模型

运行自动设置前，请先下载受支持的检查点。仓库的模型下载指南为五个入门配置及其受支持格式提供了固定命令。

2. 克隆仓库并运行向导

git clone https://github.com/Aevonix/FlashAlign.git
cd FlashAlign
bash ./install.sh --auto

向导会搜索本地模型和受支持的执行框架，选择匹配的配置，准备引擎并创建部署签名密钥。设置过程中，请选择已验证联系人或始终启用。如果选择“已验证联系人”，还需决定工具是否应继承该配置。

聊天集成会在配置后重启所选网关。本地终端设置则会直接打印启动所需的命令。

3. 确认激活

设置过程会执行激活检查，并备份其修改的配置文件。引擎的有效配置响应会确认所选配置已处于激活状态。

使用特定模型和引擎安装

需要选择特定的本地检查点时，请使用 --model-path。例如，以下命令通过 vLLM 为本地 Qwen 检查点创建独立的引擎部署：

bash ./install.sh --engine-only --backend vllm --model-path /models/qwen38-27b --yes

只能使用模型与引擎兼容性矩阵支持的组合。加载新模型或配置发生在请求时切换之前，可能需要重启引擎。

连接到现有引擎

如果兼容的推理引擎已经在运行，请在不带 --auto 的情况下启动交互式安装程序：

bash ./install.sh

设置指南介绍连接和激活流程，而引擎选择指南则说明受支持的模型与后端组合。

选择激活模式

已验证联系人

已验证联系人是默认模式。它仅将所选配置应用于与已批准的渠道、账户和联系人关联的消息。每个新回合都必须通过已验证渠道到达。仅在消息文本中放入发送者 ID 并不能获得访问权限。

此模式将消融限制在已批准的用户和渠道内，降低未经授权的用户通过恶意提示注入激活它的风险。工具输出和执行仍取决于运行框架所实现的保护措施和权限。

始终启用

始终启用会将已配置的配置应用于所有通过 FlashAlign 路由的请求，包括工具和子代理请求。所选模式会在重启后保持不变，覆盖按工具设置的对齐选项，并且不会将调用者标记为已验证。当无法应用已配置的配置时，请求将失败。

使用以下命令直接以始终启用模式安装：

bash ./install.sh --auto --mode always_on

自定义运行框架和兼容 OpenAI 的客户端可以使用项目的 始终启用网关。请注意，绕过 FlashAlign 路由或网关的请求不受 FlashAlign 控制。

批准和撤销联系人

在已验证联系人模式下，使用管理脚本批准发送者。将示例电话号码和账户替换为运行框架可识别的标识符：

python3 hermes-owner-mode/manage.py --store ~/.config/owner-mode/approvals.json approve whatsapp +15550000011 --account default

批准状态会在重启后保留，直到被撤销。在受支持的消息传输方式中，照片、语音消息、附件、转发或引用的内容以及排队的消息组都会通过运行框架保留发送者验证状态。

使用以下命令撤销联系人：

python3 hermes-owner-mode/manage.py --store ~/.config/owner-mode/approvals.json revoke whatsapp +15550000011 --account default

撤销操作会影响后续的模型请求，包括委派的工作，但不会禁用始终启用模式。

控制工具是否继承配置

已验证联系人模式允许你在安装时设置默认配置，并按名称覆盖单个工具。例如：

python3 hermes-owner-mode/manage.py --store ~/.config/owner-mode/approvals.json tool delegate_task off
python3 hermes-owner-mode/manage.py --store ~/.config/owner-mode/approvals.json tool sessions_spawn on

启用的工具可以将活动配置传递给已验证的子任务。禁用的工具使用标准模型，并且不会向其子任务传递配置。你的运行框架仍控制该工具是否获准执行。

始终启用模式会忽略这些按工具设置的标志，并将配置应用于所有已路由的工具和子代理请求。FlashAlign 会保留这些标志，以便你之后返回已验证联系人模式时继续使用。

无需重启即可切换模式

现有的运行框架部署可以在不重启的情况下切换为始终启用：

python3 hermes-owner-mode/manage.py --store ~/.config/owner-mode/approvals.json mode always_on

使用以下命令恢复基于联系人的访问：

python3 hermes-owner-mode/manage.py --store ~/.config/owner-mode/approvals.json mode verified

模式选择会在重启后保留，但切换模式不会重新启用已经被禁用的部署。对于仅引擎安装，请通过设置向导的激活步骤更改模式。

高级设置和检查提示

更改前检测环境

先运行检测模式，查看可用模型、运行框架和设置选项：

bash ./install.sh --detect

从其他目录加载配置

使用以下命令将安装程序指向自定义配置文件夹：

bash ./install.sh --profiles /path/to/profiles

配置仍需与所选模型和引擎匹配。激活前请查看配置元数据，不要假定一个配置可以在不同检查点之间通用。

检查配置内容

使用仓库的配置检查器指南，验证本地配置的模型固定版本、算子、位置、秩和哈希值。在部署下载的配置或单独存储的配置之前，这一点尤其有用。

规划加载和切换

FlashAlign 只能在引擎已加载的配置之间按请求切换。加载其他模型或配置是单独的准备步骤，并且可能会重启引擎。对于低延迟路由，请在提供请求之前加载应用所需的配置。

集成自定义客户端或运行框架

如需直接进行程序化访问，请参阅直接引擎和 Python 客户端指南。运行框架开发者可以使用自定义运行框架文档中介绍的钩子。其他消息传输方式可以实现文档所述的适配器接口。

安全性和运营注意事项

• 当需要将配置文件的使用限制在已知渠道、账户和发送者范围内时，优先选择已验证联系人。
• 只有在通过已配置路由发送的每个请求都应使用该配置文件时，才选择始终启用。
• 不要将消息正文中写入的标识符视为发送者身份的证明。
• 保持测试框架授权和工具执行控制处于启用状态；FlashAlign 不会取代这些控制。
• 完成设置或更改配置后，检查生效配置文件响应。
• 在部署到生产环境前，审查项目的安全模型、兼容性限制和验证结果。

结论

FlashAlign 提供了一种可逆方式，可应用受支持的对齐配置文件，而无需永久修改模型权重。请从固定版本的模型和兼容的引擎开始，使用安装程序准备并验证部署，并根据访问要求选择已验证联系人或始终启用。对于更复杂的部署，配置文件检查、按工具继承、直接访问引擎以及自定义测试框架钩子可提供更多控制。

FlashAlign 采用 AGPL-3.0-only 许可证，可为闭源产品和托管服务提供商业许可证。模型、配置文件和依赖项的条款彼此独立。