HEIR编译器实战：基于同态加密的私有化AI推理完整指南

在AI应用遍地开花的今天，数据隐私与安全已成为悬在开发者与企业头顶的“达摩克利斯之剑”。你是否遇到过这样的困境：想将AI能力集成到医疗、金融等敏感业务中，却因用户数据不能离境、模型参数需要保密等合规要求而束手无策？传统的云端AI推理意味着数据必须上传，这带来了巨大的隐私泄露风险。谷歌最新开源的HEIR编译器，正是为解决这一核心矛盾而来——它让基于同态加密的私有化AI推理从理论走向工程实用。本文将为你彻底拆解HEIR的技术原理、环境搭建、实战编译流程，并附上完整的代码示例与避坑指南，无论你是关注前沿技术的开发者，还是正在寻找隐私计算解决方案的架构师，都能从中获得可直接落地的知识。

1. 背景与核心概念：为什么我们需要同态加密AI推理？

在深入HEIR之前，我们必须厘清两个核心概念：AI推理与同态加密。

AI推理是指利用已经训练好的机器学习模型（如CNN、Transformer），对新的输入数据（如图片、文本）进行计算，并得到预测结果的过程。这是AI落地应用中最常见的场景。

同态加密则是一种特殊的加密技术。它允许对加密后的数据进行计算，得到的结果解密后，与对原始明文数据进行相同计算的结果一致。举个例子，假设云服务器上有加密后的数据E(5)和E(3)，服务器可以在不解密的情况下计算E(5) + E(3)，得到E(8)。用户拿到E(8)后，用自己的密钥解密，得到结果8。在整个过程中，服务器从未接触过明文数据5、3或8。

将两者结合，就产生了同态加密AI推理的范式：

1. 用户端：将待推理的敏感数据（如医疗影像）用同态加密算法加密，然后将密文发送给服务器。
2. 服务器端：在密文状态下，直接执行AI模型的计算（即推理过程）。由于是同态加密，这些计算在密文上的效果等同于在明文上计算。
3. 用户端：服务器将计算得到的加密结果返回给用户，用户解密后获得最终的明文推理结果（如疾病诊断标签）。

这种模式的优势是革命性的：服务提供商可以提供AI推理能力，但全程无法看到用户的原始数据和最终结果，完美解决了数据隐私问题。然而，其最大的瓶颈在于性能。同态加密计算比明文计算慢数个数量级，且对计算电路有特殊要求，直接将现有AI模型（如PyTorch、TensorFlow模型）转换为同态加密可执行程序极其困难。

这就是HEIR登场的意义。HEIR是一个开源编译器工具链，它的核心使命是将高级的、为明文计算设计的程序（特别是AI模型），自动编译、优化成适用于同态加密后端执行的低级表示。你可以把它想象成一个“翻译官”，把Python/PyTorch这些“人类语言”写的AI模型，翻译成同态加密硬件或库能听懂的“机器语言”。

2. 环境准备与版本说明

在开始实战之前，我们需要搭建HEIR的编译与开发环境。HEIR项目基于MLIR框架构建，因此依赖相对复杂。以下配置已在Ubuntu 20.04/22.04 LTS和macOS Monterey/Ventura上验证通过。

2.1 系统与工具链依赖

首先，确保你的系统已安装以下基础工具：

# 对于 Ubuntu/Debian sudo apt-get update sudo apt-get install -y \ build-essential \ cmake \ ninja-build \ git \ python3 \ python3-pip \ python3-venv \ libssl-dev \ pkg-config # 对于 macOS (使用 Homebrew) brew update brew install cmake ninja git pkg-config

2.2 获取HEIR源代码

HEIR项目托管在GitHub上，我们通过git克隆代码库及其子模块。

git clone https://github.com/google/heir.git cd heir git submodule update --init --recursive

关键提示：HEIR仍处于活跃开发阶段，main分支可能不稳定。建议查看项目的Release页面或使用带标签的版本进行实验，以获得更稳定的体验。

2.3 配置Python虚拟环境

HEIR的许多代码生成和测试脚本使用Python。创建一个独立的虚拟环境可以避免依赖冲突。

python3 -m venv heir-env source heir-env/bin/activate # Linux/macOS # 在Windows上使用 `heir-env\Scripts\activate` pip install --upgrade pip pip install numpy pytest

2.4 构建HEIR编译器

HEIR使用CMake进行构建。我们创建一个独立的构建目录。

cd heir mkdir build && cd build

接下来运行CMake进行配置。这里我们开启一些关键选项：

• -DHEIR_BUILD_EXAMPLES=ON：构建示例程序，对学习至关重要。
• -DCMAKE_BUILD_TYPE=Release：使用发布模式以获得更好性能（调试时可改用Debug）。

cmake -G Ninja .. \ -DCMAKE_BUILD_TYPE=Release \ -DHEIR_BUILD_EXAMPLES=ON \ -DLLVM_ENABLE_ASSERTIONS=ON

配置成功后，使用Ninja进行编译。这是一个耗时较长的过程，取决于你的机器性能。

ninja

编译成功后，你会在build/bin目录下找到一系列工具，最重要的包括heir-opt（用于优化HEIR程序）、heir-translate（用于将HEIR代码转换为目标格式）等。

2.5 验证安装

运行一个简单的测试命令，检查核心工具是否可用：

./bin/heir-opt --help | head -20

如果成功输出帮助信息，说明HEIR编译器工具链已成功安装。

3. HEIR核心原理与工作流拆解

HEIR不是一个独立的编程语言，而是一个基于MLIR的多层编译器基础设施。理解其工作流是使用的关键。

3.1 MLIR与HEIR的层次结构

MLIR允许定义不同抽象层次的“方言”。HEIR利用这一点，构建了一个从高层算法到底层同态加密执行的下降管道：

1. Tensor/Arith 层：这是输入层，表示原始的、未加密的张量运算。可以来自PyTorch导出的模型或手写的算法。
2. HEIR Secret 层：这是HEIR引入的核心抽象层。在这一层，数据类型被标记为“秘密的”，即它们代表将来会被加密的数据。运算（如加、乘）被转换为同态加密友好的操作，但尚未绑定到具体的加密方案。
3. CGGI/TFHE/BFV/BGV 层：这些是具体的同态加密方案方言层。编译器将“秘密”操作 lowering 到特定方案的原语上，例如TFHE的bootstrapping操作或BFV的multiply操作。
4. Runtime Calls 层：最终，特定方案的操作被转换为对底层同态加密库（如SEAL、TFHE-rs）的函数调用。

HEIR编译器的工作，就是安全、正确、高效地将第1层的程序，通过第2层和第3层，最终转换为第4层的代码。

3.2 一个简单的编程模型示例

让我们看一个HEIR程序在“Secret”方言下的样子。假设我们想计算一个加密的线性函数f(x) = a * x + b。

// 文件：linear.mlir func.func @main(%secret_x : !heir.secret<si32>) -> !heir.secret<si32> { // 定义明文系数（在实际中，这些也可能被加密或由一方持有） %plain_a = arith.constant 5 : i32 %plain_b = arith.constant 3 : i32 // 将明文系数提升为“秘密”类型，以便与秘密数据运算 %secret_a = heir.secret.cast %plain_a : i32 to !heir.secret<si32> %secret_b = heir.secret.cast %plain_b : i32 to !heir.secret<si32> // 秘密乘法: a * x %mul = heir.secret.mul %secret_a, %secret_x : !heir.secret<si32> // 秘密加法: (a*x) + b %result = heir.secret.add %mul, %secret_b : !heir.secret<si32> // 返回加密结果 func.return %result : !heir.secret<si32> }

这个程序定义了一个函数，输入一个加密的32位有符号整数%secret_x，输出一个加密的32位有符号整数。heir.secret.mul和heir.secret.add就是HEIR在秘密域定义的运算。关键点：这个.mlir文件描述的是计算逻辑，而不依赖于具体的同态加密库。接下来，HEIR编译器会将其转换为针对特定后端（如BFV）的C++代码。

4. 完整实战：编译一个同态加密的AI模型子图

现在，我们将完成一个从高级表示到生成可集成代码的完整流程。本例将把一个简单的多项式计算图（模拟一个微小的AI模型层）通过HEIR编译为基于SEAL库（实现BFV方案）的C++代码。

4.1 定义输入计算图

我们创建一个更贴近AI的例子：一个包含加法、乘法和激活函数（近似为多项式）的微型网络层。首先，在Python中定义这个计算图，并将其转换为MLIR的Tensor方言。

# 文件：generate_mlir.py import torch import torch.nn as nn import torch.mlir from torch.mlir.dialects.torch import register_dialect as register_torch_dialect # 1. 定义一个简单的模块 class TinyNet(nn.Module): def forward(self, x): # 假设 x 是加密的输入 # 第一层：线性变换 y = x * weight + bias weight = torch.tensor([[2.0]], dtype=torch.float32) bias = torch.tensor([1.0], dtype=torch.float32) y = torch.matmul(x, weight) + bias # 一个简单的多项式激活（模拟ReLU的近似）：z = y^2 + 0.5*y z = y * y + 0.5 * y return z # 2. 实例化并生成MLIR model = TinyNet() example_input = torch.tensor([[3.0]], dtype=torch.float32) # 使用Torch-MLIR将模型导出为MLIR（Linalg方言） mlir_module = torch.mlir.export(model, example_input) mlir_str = str(mlir_module) # 3. 保存到文件 with open('tiny_net.mlir', 'w') as f: f.write(mlir_str) print("MLIR generated and saved to tiny_net.mlir")

运行此脚本后，会得到一个tiny_net.mlir文件，其中包含基于linalg和tensor等方言的MLIR代码。

4.2 使用HEIR进行 lowering 和优化

接下来，我们使用HEIR编译器工具链，将通用的MLIR lowering 到HEIR秘密方言，并进一步优化。

# 进入HEIR构建目录 cd /path/to/heir/build # 第一步：将通用的Linalg/Tensor MLIR转换为HEIR Secret方言 # heir-opt 是执行MLIR转换和优化的主要工具 ./bin/heir-opt /path/to/tiny_net.mlir \ --convert-linalg-to-loops \ --lower-affine \ --convert-scf-to-cf \ --convert-arith-to-emulated-secret \ --canonicalize \ --cse \ -o tiny_net_secret.mlir

参数解释：

• --convert-*-to-*：一系列预定义的 lowering 通道，将高级运算逐步降级。
• --convert-arith-to-emulated-secret：关键步骤。将算术运算（arith.addf,arith.mulf）转换为在秘密类型上的模拟运算（heir.secret.add,heir.secret.mul）。
• --canonicalize和--cse：进行规范化和公共子表达式消除等优化。

生成的tiny_net_secret.mlir文件包含了用!heir.secret类型标记的秘密计算。

4.3 针对具体同态加密方案生成代码

现在，我们将秘密计算 lowering 到具体的BFV同态加密方案，并生成C++代码。假设我们选择使用微软的SEAL库作为BFV的后端。

# 第二步：从HEIR Secret方言 lowering 到BFV方言，并生成C++运行时调用 ./bin/heir-translate tiny_net_secret.mlir \ --emit-secret-to-bfv \ --bfv-parameter-set=small \ # 使用一个小的参数集（仅用于测试！） --emit-crt \ -o tiny_net_bfv.cpp

参数解释：

• --emit-secret-to-bfv：指定 lowering 到BFV方案。
• --bfv-parameter-set=small：选择BFV的加密参数。small仅用于功能验证，实际部署必须根据安全要求和性能选择参数。
• --emit-crt：生成包含运行时调用的C++代码。
• -o tiny_net_bfv.cpp：输出C++文件。

4.4 生成的C++代码解析与集成

打开生成的tiny_net_bfv.cpp，你会看到类似下面的结构：

// 文件：tiny_net_bfv.cpp (简化版) #include <vector> #include "seal/seal.h" using namespace seal; void encrypted_tiny_net( Ciphertext &encrypted_input, // 输入的密文 const SEALContext &context, const PublicKey &public_key, const RelinKeys &relin_keys, Ciphertext &encrypted_output // 输出的密文 ) { auto &parms = context.first_context_data()->parms(); auto coeff_modulus = parms.coeff_modulus(); size_t coeff_mod_count = coeff_modulus.size(); auto plain_modulus = parms.plain_modulus(); // 编码明文系数 weight=2, bias=1 Plaintext plain_weight, plain_bias, plain_half; BatchEncoder batch_encoder(context); std::vector<uint64_t> pod_matrix(/*...尺寸...*/, 0ULL); // ... 编码过程 ... pod_matrix[0] = 2; batch_encoder.encode(pod_matrix, plain_weight); // ... 类似地编码 bias=1 和 0.5 ... Evaluator evaluator(context); // 密文乘法: encrypted_input * plain_weight Ciphertext encrypted_y; evaluator.multiply_plain(encrypted_input, plain_weight, encrypted_y); // 密文加法: encrypted_y + plain_bias evaluator.add_plain_inplace(encrypted_y, plain_bias); // 计算 y^2: 需要重线性化 Ciphertext encrypted_y_sq; evaluator.square(encrypted_y, encrypted_y_sq); evaluator.relinearize_inplace(encrypted_y_sq, relin_keys); // 计算 0.5 * y Ciphertext encrypted_half_y; evaluator.multiply_plain(encrypted_y, plain_half, encrypted_half_y); // 最终结果: y^2 + 0.5*y evaluator.add(encrypted_y_sq, encrypted_half_y, encrypted_output); }

这个函数encrypted_tiny_net就是HEIR为我们生成的、可以直接集成到应用程序中的核心函数。它接收SEAL库的密文、公钥、重线性化密钥等，在密文上执行了与原始PyTorch模型等价的计算。

4.5 编译与运行生成的代码

要运行此代码，你需要安装SEAL库并链接。

# 1. 安装SEAL（以v4.1为例） git clone https://github.com/microsoft/SEAL.git cd SEAL cmake -S . -B build -DSEAL_BUILD_EXAMPLES=OFF -DSEAL_BUILD_TESTS=OFF cmake --build build --target install # 2. 编写一个主程序来调用生成的函数 // 文件：main.cpp #include "tiny_net_bfv.cpp" // 包含生成的计算函数 #include <iostream> #include "seal/seal.h" int main() { // 初始化SEAL上下文（参数必须与生成时一致！） seal::EncryptionParameters parms(seal::scheme_type::bfv); size_t poly_modulus_degree = 4096; // 示例参数 parms.set_poly_modulus_degree(poly_modulus_degree); parms.set_coeff_modulus(seal::CoeffModulus::BFVDefault(poly_modulus_degree)); parms.set_plain_modulus(seal::PlainModulus::Batching(poly_modulus_degree, 20)); seal::SEALContext context(parms); // 生成密钥 seal::KeyGenerator keygen(context); auto secret_key = keygen.secret_key(); auto public_key = keygen.create_public_key(); auto relin_keys = keygen.create_relin_keys(); seal::Encryptor encryptor(context, public_key); seal::Decryptor decryptor(context, secret_key); seal::BatchEncoder batch_encoder(context); // 准备明文输入（例如 3.0） std::vector<uint64_t> pod_matrix = {3}; seal::Plaintext plain_input; batch_encoder.encode(pod_matrix, plain_input); // 加密输入 seal::Ciphertext encrypted_input; encryptor.encrypt(plain_input, encrypted_input); // 调用HEIR生成的函数进行加密推理 seal::Ciphertext encrypted_output; encrypted_tiny_net(encrypted_input, context, public_key, relin_keys, encrypted_output); // 解密输出 seal::Plaintext plain_output; decryptor.decrypt(encrypted_output, plain_output); std::vector<uint64_t> result; batch_encoder.decode(plain_output, result); std::cout << "Encrypted inference result: " << result[0] << std::endl; // 验证：对于x=3, f(x)= (3*2+1)^2 + 0.5*(3*2+1) = 7^2 + 3.5 = 49 + 3.5 = 52.5 // 由于BFV处理整数，结果会是52或53，取决于编码和参数设置 return 0; }

# 3. 编译并运行 g++ -std=c++17 main.cpp -o main -lseal-4.1 ./main

如果一切顺利，程序将输出加密计算后的结果。请注意：由于同态加密参数和编码的限制，输出可能是一个近似整数，这与纯明文浮点计算的结果会有差异，这是同态加密计算的一个特点。

5. 常见问题与排查思路

在实践HEIR和同态加密AI推理的过程中，你一定会遇到各种问题。下表总结了常见问题及其解决方法：

6. 最佳实践与工程建议

将HEIR用于实际项目，远不止跑通一个示例。以下是从工程化角度出发的最佳实践。

6.1 安全第一：参数选择与审计

同态加密的安全性完全依赖于加密参数。切勿在生产环境使用small或tiny参数集。

• 理解参数：核心参数poly_modulus_degree（多项式次数）和coeff_modulus（系数模数）直接关联安全强度（如128位、192位安全等级）。必须使用SEAL库的SecurityLevel枚举或第三方工具（如Lattigo的参数选择器）来验证参数安全性。
• 独立审计：生成的加密代码和参数应由专业的安全团队或密码学专家进行审计。HEIR作为编译器，可能引入非密码学层面的逻辑错误。
• 密钥管理：HEIR生成的是计算逻辑，密钥（公钥、私钥、重线性化密钥）必须在你的应用系统中安全地生成、存储和分发。私钥绝不能泄露给服务器。

6.2 性能优化：从模型设计到编译选项

1. 模型层面：

   • 量化与低精度：同态加密处理整数或定点数更高效。在训练模型时就考虑使用量化感知训练，将权重和激活值限制在较小整数范围。
   • 激活函数替代：用多项式（如x^2 + 0.5x）近似ReLU、Sigmoid等非线性函数。研究并选择计算深度浅、近似度高的多项式。
   • 网络结构简化：优先选择计算友好的层，如卷积层在特定参数下可以通过SIMD批处理获得加速，而注意力机制可能非常昂贵。

2. HEIR编译层面：

   • 利用优化通道：仔细研究heir-opt的--help输出，尝试不同的优化通道组合，如--heir-simd-vectorize（如果后端支持）可能自动利用批处理特性。
   • 自定义 lowering：对于性能关键部分，可以考虑手写或定制 lowering 规则，将特定计算模式映射到更高效的同态原语上。

6.3 集成与部署模式

• 客户端-服务器模式：这是最典型的场景。客户端负责加密数据、解密结果；服务器运行HEIR生成的加密计算函数。通信协议需考虑密文数据量大的问题（可能需要流式传输）。
• 边缘计算模式：将HEIR生成的轻量级加密计算模块部署在边缘设备，对本地采集的敏感数据（如摄像头画面）进行初步加密处理，再上传至云进行更深层分析。
• 与可信执行环境结合：将同态加密与TEE（如Intel SGX）结合。在TEE内进行解密和部分明文计算，仅将最敏感的核心计算用同态加密外包，以平衡安全与性能。

6.4 测试与验证策略

1. 端到端正确性测试：建立自动化测试流水线，用随机生成的输入数据，分别运行原始明文模型和HEIR生成的加密推理管道，对比两者的输出。由于编码误差，需要定义可接受的误差范围。
2. 回归测试：每当模型更新或HEIR工具链升级时，重新运行测试套件，确保功能正确性和性能没有退化。
3. 性能基准测试：在固定的安全参数和硬件配置下，记录推理延迟、内存占用和通信开销，作为性能基线，指导后续优化。

7. 总结与学习路线

HEIR的发布标志着同态加密从密码学实验室走向工程化应用的关键一步。它通过编译技术，抽象了底层复杂的密码学细节，让AI开发者能够以相对熟悉的方式触及隐私计算的前沿。

通过本文，你应该已经掌握了：

1. 理解核心价值：明确了同态加密在解决AI推理数据隐私问题上的不可替代性。
2. 搭建实战环境：成功配置了HEIR的编译与开发环境，这是所有工作的基础。
3. 洞悉工作原理：理解了HEIR基于MLIR的多层 lowering 工作流，从高级算法到加密运行时调用的转换过程。
4. 完成完整流程：亲手将一个小型PyTorch模型通过HEIR编译为基于SEAL库的C++加密推理函数，并成功运行验证。
5. 具备排错能力：能够诊断和解决从环境配置、编译错误到结果偏差的常见问题。
6. 规划工程落地：了解了安全参数选择、性能优化和系统集成的最佳实践。

下一步的学习路线建议：

• 深入MLIR：HEIR的强大源于MLIR。学习MLIR的核心概念（方言、操作、转换、Pass）将让你能更灵活地使用甚至扩展HEIR。
• 钻研同态加密库：不满足于HEIR生成的代码，直接学习SEAL、OpenFHE或TFHE-rs等库的API，理解不同加密方案（BFV, BGV, CKKS, TFHE）的优劣与适用场景。
• 探索完整模型编译：尝试将真实的、小规模的图像分类（如MNIST上的CNN）或文本模型编译为加密版本，挑战更复杂的计算图管理和精度控制问题。
• 关注社区动态：HEIR是一个活跃的开源项目，关注其GitHub仓库的Issue、Discussion和Release，及时获取最新特性和修复。

隐私计算是AI可持续发展的必由之路，而HEIR这样的工具正在为其铺平道路。虽然前路仍有性能、易用性等诸多挑战，但亲手实践一次从模型到加密部署的完整流程，无疑是拥抱这个未来趋势的最佳起点。