1. 项目概述为什么Heir与同态加密编译器值得你投入时间如果你正在数据安全、隐私计算或者AI推理这些领域摸爬滚打最近肯定没少听到“同态加密”这个词。它就像一个“魔法黑盒”允许你在加密的数据上直接进行计算得到的结果解密后与对原始明文数据计算的结果一模一样。这意味着你可以把敏感数据比如医疗记录、财务信息加密后丢给云服务商做分析对方全程看不到数据内容却能把分析结果正确返回给你。这个愿景很美但现实是同态加密方案极其复杂参数选择、电路优化、性能调优每一步都足以让一个工程师头疼好几天。这就是Heir出现的原因。它不是又一个同态加密库而是一个编译器。你可以把它理解为一个“翻译官”和“优化大师”。你的任务是用高级语言比如C描述一个计算逻辑Heir的工作就是把这个逻辑“翻译”成最适合在某种同态加密方案如BGV、BFV、CKKS下高效执行的、由底层同态操作组成的程序。它帮你自动处理了最繁琐、最容易出错的部分电路表示、参数推导、噪声管理、调度优化。简单说Heir的目标是让开发者像写普通程序一样使用同态加密把专业性的门槛从“密码学博士”降低到“熟练的软件工程师”。我花了相当一段时间深入使用和测试Heir这个过程里踩过的坑、获得的效率提升让我觉得有必要把这些经验系统性地分享出来。这篇教程不会只停留在“Hello World”式的表面操作我会带你从最根本的原理理解为什么需要编译器一步步拆解Heir的架构直到你能用它解决一个中等复杂度的实际问题。无论你是隐私计算领域的研究者还是正在寻找落地方案的全栈工程师这篇文章都能给你提供一条清晰的、可实操的路径。2. Heir核心架构与设计哲学拆解在直接敲命令之前我们必须先理解Heir的“大脑”是如何工作的。这能让你在后续遇到问题时不是盲目地搜索错误代码而是能进行有根据的推理和排查。2.1 同态加密为什么需要编译器传统编程中编译器如GCC、Clang将高级语言代码转换为机器码优化目标是速度、内存占用。同态加密编程则完全不同它的“机器”是一套复杂的数学运算规则。这里有几个核心挑战噪声预算管理同态加密中的密文都带有“噪声”。每一次计算加、乘、旋转都会消耗噪声预算。一旦预算耗尽解密就会失败。编译器必须精确估算每一步操作的噪声增长并智能地插入“自举”操作来刷新噪声这就像在长跑中规划补水点。参数化地狱加密方案有数十个参数多项式模数、系数模数、明文模数等。这些参数共同决定了安全性等级、可计算深度和性能。手动选择参数如同走钢丝要么安全性不足要么性能极差。编译器需要根据你的计算电路自动推导出满足安全性和功能性的最小参数集。计算图优化你的程序会被表示为一个计算图在Heir里基于MLIR。编译器可以在这个图上做文章比如合并连续的加法、重排乘法顺序以减少乘法深度乘法比加法消耗更多噪声、利用SIMD批处理特性进行向量化计算。这些优化带来的性能提升可能是数量级的。Heir的设计哲学正是将开发者从上述挑战中解放出来。它提供了一套中间表示和一系列从高到低的转换与优化通道让你专注于业务逻辑。2.2 Heir的层次化编译流程Heir的编译流程可以类比为一场接力赛数据你的程序在不同层级的“运动员”手中传递、变形、优化。前端输入目前Heir主要接受两种输入。一是通过heir-opt工具直接处理MLIR方言文件.mlir这是最直接的方式。二是未来规划中可能会支持从类似Circuit Python或特定DSL领域特定语言编译而来。我们教程主要聚焦于MLIR输入因为这是最灵活和底层的方式。tosa与linalg层你的计算逻辑首先会被表达在相对高层的MLIR方言中如tosa面向张量操作或linalg线性代数泛型。这一层描述的是“做什么”比如两个矩阵相乘一个向量做激活函数。secret方言层这是Heir引入的核心抽象层。在这一层数据类型被标记为secret.secretT表示这是一个加密的、类型为T的秘密值。所有操作如secret.addsecret.mul都变成了在秘密值上的操作。这一层是算法逻辑与具体加密方案解耦的关键。cggi方言层全称可能是“Code Generation for Garbled Circuits or Homomorphic Encryption”的某种变体这一层更接近底层同态加密的原语。它包含了更具体的、与方案相关的操作提示。bgvbfvckks方言层这是后端层。编译器根据目标方案将上层操作最终 lowering降级到具体的同态加密方言。例如一个secret.mul在BGV方案下会被转换为特定的多项式乘法与重线性化操作序列。在这一层具体的参数如环维度N 模数链q被确定并注入。代码生成最后Heir可以将底层的、参数化的同态加密操作序列输出为目标代码。目前它主要生成两种一是C代码其中会调用具体的同态加密库如OpenFHE, SEAL的API二是MLIR代码供其他工具链进一步处理或分析。注意当前Heir仍处于活跃开发阶段并非所有通路都已完全实现或达到生产级稳定。例如从高级语言到tosa的完整前端以及到某些加密库的代码生成器可能还在完善中。但这不影响我们学习其核心思想和当前可用的强大功能。理解了这个流程你就知道在编译过程中你的程序经历了怎样的“洗礼”。接下来我们就要亲手搭建环境让这个流程跑起来。3. 从零搭建Heir开发与实验环境搭建Heir的环境是第一步也是劝退很多人的一步。因为它依赖于LLVM/MLIR这个庞大的工具链。别担心我会提供一条最清晰、坑最少的路径。我们选择从源码编译这能给你最大的灵活性和调试能力。3.1 系统准备与依赖安装我强烈推荐在Ubuntu 20.04 LTS或22.04 LTS上进行开发这是与LLVM/MLIR生态兼容性最好的环境。如果你用Windows建议使用WSL2并安装Ubuntu发行版。首先更新系统并安装基础编译工具和依赖sudo apt update sudo apt upgrade -y sudo apt install -y \ build-essential \ cmake \ ninja-build \ git \ python3 \ python3-pip \ python3-venv \ libz-dev \ libncurses-dev接下来安装一些可能需要的库特别是如果未来需要链接其他HE库如SEALsudo apt install -y \ libssl-dev \ pkg-config3.2 获取LLVM/MLIR与Heir源码Heir是LLVM项目的一个子项目因此我们需要先获取LLVM的源码。克隆LLVM项目我们不需要整个LLVM历史所以使用--depth 1来节省时间和空间。git clone --depth 1 https://github.com/llvm/llvm-project.git cd llvm-project在LLVM项目中克隆Heir仓库Heir应该作为llvm-project的一个子目录存在。git clone --depth 1 https://github.com/google/heir.git llvm/projects/heir是的路径是llvm/projects/heir这是LLVM外部项目的标准存放位置。3.3 配置与编译这是最耗时但也最关键的一步。我们使用CMake进行配置并采用Ninja作为构建系统比Make更快。创建构建目录并进入mkdir build cd build运行CMake配置这条命令设置了安装前缀、构建类型并启用了Heir项目和一些我们需要的LLVM子项目如mlir。cmake -G Ninja ../llvm \ -DCMAKE_INSTALL_PREFIX../install \ -DCMAKE_BUILD_TYPERelease \ -DLLVM_ENABLE_PROJECTSmlir \ -DLLVM_EXTERNAL_PROJECTSheir \ -DLLVM_EXTERNAL_HEIR_SOURCE_DIR../llvm/projects/heir \ -DMLIR_ENABLE_BINDINGS_PYTHONON \ -DLLVM_TARGETS_TO_BUILDhost \ -DLLVM_ENABLE_ASSERTIONSON-DCMAKE_INSTALL_PREFIX指定编译后文件的安装位置放在源码树外是个好习惯。-DCMAKE_BUILD_TYPERelease生成优化版本性能更好。如果是深度调试可以改为Debug但编译时间更长产物更大。-DLLVM_ENABLE_PROJECTSmlir我们主要需要MLIR。-DLLVM_EXTERNAL_PROJECTS和-DLLVM_EXTERNAL_HEIR_SOURCE_DIR告诉CMake Heir项目的位置。-DMLIR_ENABLE_BINDINGS_PYTHONON启用Python绑定方便以后用Python脚本驱动MLIR/Heir非常有用。-DLLVM_ENABLE_ASSERTIONSON在Release模式下也启用断言有助于在开发早期发现问题。开始编译使用Ninja进行并行编译-j后面的数字根据你的CPU核心数调整通常为核心数或核心数1。ninja -j8这个过程可能需要30分钟到数小时取决于你的机器性能。泡杯茶耐心等待。安装编译成功后将工具安装到之前指定的前缀目录。ninja install配置环境变量为了能方便地使用heir-opt等工具将安装目录下的bin文件夹加入PATH。echo export PATH/path/to/your/llvm-project/install/bin:$PATH ~/.bashrc source ~/.bashrc请将/path/to/your/llvm-project替换为你的实际路径。现在在终端中输入heir-opt --help如果能看到一长串帮助信息恭喜你环境搭建成功了实操心得编译过程最容易出错的是依赖缺失或版本冲突。如果CMake报错仔细阅读错误信息通常是缺少某个-dev版本的库。另一个常见问题是内存不足编译LLVM需要大量内存确保你的机器有至少8GB可用内存如果使用虚拟机或WSL请分配足够的内存和交换空间。4. 编写你的第一个Heir程序一个加密的加法器理论说了这么多是时候动手了。我们将创建一个最简单的MLIR程序它描述了两个加密整数的加法然后让Heir将其编译。4.1 理解MLIR语法基础MLIRMulti-Level IR是一种灵活的编译器中间表示。它看起来有点像LLVM IR但更可读。一个基本的MLIR模块结构如下module { // 函数定义 func.func main() - i32 { // 操作 %c1 arith.constant 1 : i32 %c2 arith.constant 2 : i32 %sum arith.addi %c1, %c2 : i32 return %sum : i32 } }module顶级容器。func.func定义一个函数。main是函数名- i32指定返回类型是32位整数。%c1 arith.constant 1 : i32定义一个SSA值%c1它是一个arith方言下的常量操作值为1类型为i32。arith.addi整数加法操作。每行末尾的: i32指定了结果的类型。4.2 创建使用secret方言的MLIR文件我们创建一个名为simple_add.mlir的文件。这次我们要使用Heir的secret方言。// simple_add.mlir module { // 声明一个函数它接受两个秘密整数返回一个秘密整数 func.func main(%arg0: !secret.secreti32, %arg1: !secret.secreti32) - !secret.secreti32 { // 在秘密值上执行加法操作 %result secret.add %arg0, %arg1 : !secret.secreti32 return %result : !secret.secreti32 } }!secret.secreti32这是Heirsecret方言中的类型表示一个加密的i32类型值。!前缀表示这是一个MLIR中的“类型”。secret.addsecret方言中的加法操作。它表示在密文状态下的加法。这个文件描述了一个非常简单的电路两个加密输入一个加密输出中间是一个同态加法。4.3 使用heir-opt进行编译和降级现在我们使用heir-opt工具来处理这个MLIR文件。heir-opt就像MLIR的瑞士军刀可以加载各种方言并运行指定的“编译通道”。我们先尝试一个简单的通道将secret方言转换到cggi方言并做一些基础优化heir-opt simple_add.mlir \ --convert-secret-to-cggi \ --cggi-optimize \ --canonicalize--convert-secret-to-cggi将secret方言的操作转换为cggi方言。--cggi-optimize在cggi层级运行一些优化。--canonicalize这是一个通用的MLIR规范化传递用于清理冗余操作、简化表达式等。运行后你会在终端看到输出类似下面的MLIR代码经过简化module { func.func main(%arg0: !cggi.ciphertexti32, %arg1: !cggi.ciphertexti32) - !cggi.ciphertexti32 { %0 cggi.add %arg0, %arg1 : !cggi.ciphertexti32 return %0 : !cggi.ciphertexti32 } }可以看到!secret.secret类型变成了!cggi.ciphertextsecret.add操作变成了cggi.add。我们向底层又迈进了一步。4.4 向具体同态加密方案BGV降级接下来我们尝试将其降级到具体的BGV方案。这需要更多的参数和更复杂的通道。我们创建一个更完整的编译命令脚本compile.sh#!/bin/bash # compile.sh INPUT_MLIRsimple_add.mlir OUTPUT_MLIRsimple_add_bgv.mlir heir-opt ${INPUT_MLIR} \ --convert-secret-to-cggi \ --cggi-optimize \ --canonicalize \ --lower-cggi-to-bgvpoly-mod-degree1024 plaintext-modulus65537 \ --bgv-parameter-insertion \ --canonicalize \ --cse \ ${OUTPUT_MLIR} 21 echo 编译完成输出见 ${OUTPUT_MLIR}--lower-cggi-to-bgv这是关键的一步将cggi操作降级到bgv方言。我们通过属性传递了一些BGV的初始参数poly-mod-degree1024多项式环维度与安全性和性能相关plaintext-modulus65537明文模数一个常见的素数选择。--bgv-parameter-insertion根据计算电路插入或完善BGV方案所需的详细参数。--cse公共子表达式消除一种常见的编译器优化。运行bash compile.sh后查看simple_add_bgv.mlir你会看到代码变得更加底层出现了bgv.add等操作并且模块顶部可能多了很多描述参数的属性。这就是你的计算电路在BGV同态加密世界中的“蓝图”。注意事项参数选择如poly-mod-degree和plaintext-modulus不是随意的。它们需要满足数学上的约束如模数之间互质并且其大小直接关联到安全强度通常用比特安全位数衡量如128位安全和电路计算深度。在这个简单例子中我们用了经验值。对于真实应用Heir的自动化参数推导功能至关重要它可以确保你选择的参数既安全又能支持你的计算。5. 深入核心实现一个加密的线性回归预测现在我们来挑战一个更贴近现实的例子一个加密的线性回归单点预测。假设我们有一个训练好的模型y w * x b其中权重w和偏置b是已知的明文或由模型提供方加密输入特征x是用户提供的加密数据。我们需要在密文状态下计算y。5.1 设计MLIR计算图我们创建一个新的文件lr_predict.mlir。为了更真实我们假设数据是定点数或整数。这里我们用i32模拟但实际中CKKS方案更适用于浮点计算。// lr_predict.mlir module { // 函数加密预测 // %enc_x: 加密的输入特征 // %w: 明文权重 (在实际中可能也是加密的这里简化) // %b: 明文偏置 func.func encrypted_predict(%enc_x: !secret.secreti32, %w: i32, %b: i32) - !secret.secreti32 { // 1. 密文乘法: w * enc_x // 注意secret.mul 要求两个操作数都是 secret 类型。 // 我们需要将明文 w 提升编码为“透明秘密”类型。这里假设有一个操作可以处理。 // 为了简化演示我们假设 %w 和 %b 已经是某种可同态操作的形式。 // 更真实的做法是使用 secret.encode 或类似操作。 // 此处我们使用一个假设的 secret.mul_plain 操作实际方言可能不同。 %mul secret.mul_plain %enc_x, %w : (!secret.secreti32, i32) - !secret.secreti32 // 2. 密文加法: (w*x) b // 同样需要一个与明文加的操作。 %result secret.add_plain %mul, %b : (!secret.secreti32, i32) - !secret.secreti32 return %result : !secret.secreti32 } // 一个简单的测试主函数 func.func main() - i32 { // 模拟明文值 %w_val arith.constant 3 : i32 %b_val arith.constant 5 : i32 // 模拟一个加密输入在实际中这个值来自客户端 // 我们用一个普通值模拟并标记它“应该”是加密的。这里为了流程演示。 %dummy_enc_x arith.constant 10 : i32 // 我们需要将普通值转换为 secret 类型这通常由客户端加密完成。 // 在编译器测试中我们可以用一个假的操作来模拟。 %enc_x unrealized_conversion_cast %dummy_enc_x : i32 to !secret.secreti32 // 调用加密预测函数 %enc_result func.call encrypted_predict(%enc_x, %w_val, %b_val) : (!secret.secreti32, i32, i32) - !secret.secreti32 // 解密结果模拟。在实际中发生在客户端。 %result unrealized_conversion_cast %enc_result : !secret.secreti32 to i32 return %result : i32 // 期望得到 3*10535 } }这个例子比纯加法复杂。它引入了几个关键概念密文-明文混合运算同态加密不仅支持密文-密文运算如secret.add也支持密文-明文运算如secret.add_plain后者通常开销更小。我们的代码体现了对这种操作的需求。函数抽象我们将核心的加密预测逻辑封装成了函数encrypted_predict这有利于模块化。类型转换模拟我们用unrealized_conversion_cast这个MLIR通用操作来模拟加密和解密过程。在实际的Heir工作流中会有更具体的方言操作来处理编码Encode和解码Decode。5.2 构造并运行完整的编译管道对于这个稍复杂的例子我们需要一个更精细的编译管道。我们创建一个pipeline.mlir文件来定义这个管道然后使用heir-opt来执行。# 首先将 secret 方言降低到 cggi heir-opt lr_predict.mlir \ --convert-secret-to-cggi \ --cggi-optimize \ --canonicalize \ --cse \ -o lr_predict_cggi.mlir # 然后针对BGV方案进行 lowering 和参数化 # 假设我们目标是一个能支持一次乘法和若干加法的电路 heir-opt lr_predict_cggi.mlir \ --lower-cggi-to-bgvpoly-mod-degree2048 plaintext-modulus65537 \ --bgv-parameter-insertion \ --bgv-optimize \ --canonicalize \ -o lr_predict_bgv.mlir echo “查看BGV层级的输出” cat lr_predict_bgv.mlir | head -50查看lr_predict_bgv.mlir你会看到大量的bgv.mulbgv.addbgv.relinearize等操作以及一长串定义了多项式环、模数链等详细参数的属性。这就是你的线性回归预测电路被彻底“翻译”成BGV同态加密底层操作的样子。编译器可能已经自动插入了必要的噪声管理操作如自举如果乘法深度超过1并优化了操作顺序。5.3 性能分析与优化点审视生成底层表示后我们可以进行一些分析乘法深度数一数连续的bgv.mul操作最长路径。这决定了所需的最小模数链长度和自举频率。我们的例子中只有一次乘法深度为1非常轻松。参数合理性检查自动生成的参数。poly-mod-degree2048可能比之前简单加法的1024要大因为我们需要支持乘法。编译器通过--bgv-parameter-insertion应该已经根据你的计算电路和指定的安全级别虽然我们例子中没显式指定但可能有默认值计算出了合适的参数。优化机会如果计算更复杂你可以回到高层的secret或cggi表示尝试手动进行一些优化。例如平衡乘法树如果有很多连续乘法调整顺序可以减少最坏情况下的乘法深度。利用SIMD如果使用BGV/BFV的打包加密Batch Encoding一个密文可以包含多个明文数。编译器可能自动进行了向量化但你需要确保你的算法适合批处理。实操心得在编写MLIR时时刻想着你是在描述一个“计算电路”而不是一个“顺序执行的程序”。编译器会全局地看待这个电路图。好的电路描述比如避免不必要的依赖、暴露并行性能给后端优化器更多发挥空间。另外密切关heir-opt每个pass的输出理解每一步转换对你的代码做了什么这是调试和精进的关键。6. 常见问题、调试技巧与进阶方向在实际使用Heir的过程中你一定会遇到各种报错和意料之外的行为。这里我整理了一份“避坑指南”。6.1 编译与运行时报错排查错误现象可能原因排查步骤与解决方案heir-opt: error: unknown pass ‘xxx’1. Pass名称拼写错误。2. Heir未正确编译某些Pass未启用。1. 运行heir-opt --list-passes查看所有可用Pass核对名称。2. 确认编译时CMake配置正确特别是Heir项目是否被正确包含。重新编译安装。error: failed to legalize operation ‘secret.yyy’操作yyy在当前 lowering 阶段无法被合法化即找不到更低层的操作来替换它。1. 检查是否遗漏了必要的转换Pass。例如secret方言的操作需要先通过--convert-secret-to-cggi转换。2. 检查操作是否在目标后端如BGV中被支持。某些复杂操作可能需要分解。编译出的BGV参数看起来不安全或性能极差1. 自动参数推导失败或使用了不合适的启发式规则。2. 手动指定的初始参数如poly-mod-degree与电路复杂度不匹配。1. 尝试显式指定安全级别参数如果Heir支持如--bgv-param-insertion”security-bits128″。2. 增加poly-mod-degree如从1024到2048, 4096或调整模数链。参考同态加密库如OpenFHE的参数选择工具来验证。生成的代码无法用目标HE库编译Heir的代码生成器如到OpenFHE的生成器可能不完整或与库的API版本不匹配。1. 查看Heir项目include/和lib/目录下对应后端的代码生成逻辑。2. 目前可能更适合将Heir输出作为“参考方案”手动将其转换为最终的库调用代码。这是前沿工具常见的状况。性能远低于预期1. 未启用优化Pass。2. 乘法深度过大导致需要频繁自举或使用超大参数。3. 未利用批处理SIMD。1. 确保在管道中加入了--cggi-optimize--bgv-optimize--canonicalize--cse等优化Pass。2. 使用heir-opt –-analyze-mult-depth如果存在等分析工具查看电路深度重构算法减少连续乘法。3. 研究如何在secret层表达向量化计算以利用打包加密。6.2 调试与可视化技巧分阶段输出就像我们之前做的那样在每个重要的编译阶段如secret-cggicggi-bgv后输出到文件。逐文件对比看你的操作是如何被 lowering 的。使用MLIR的打印调试在MLIR文件中插入debug操作或使用mlir-opt的–-print-ir-after-all等选项可以打印出每个Pass之后的IR状态但信息量巨大建议在小型用例上使用。简化测试用例当遇到复杂电路的错误时总是尝试创建一个最小的、能复现问题的最简例子。这能帮你快速定位是哪个操作或哪种模式导致了问题。6.3 进阶探索方向当你掌握了Heir的基础后可以朝这些方向深入集成真实后端尝试让Heir生成调用真实同态加密库如OpenFHE或Microsoft SEAL的C代码。这需要你深入研究Heir中lib/Target/目录下的代码生成器并可能需要进行一些适配工作。这是将Heir用于实际项目的前提。探索CKKS方案BGV/BFV适合整数运算而CKKS方案支持定点近似运算更适合机器学习推理。研究Heir对CKKS方言的支持并尝试编译一个包含激活函数如多项式近似的ReLU的神经网络层。贡献代码Heir是一个开源项目。如果你发现了Bug或者实现了某个优化、支持了某个新的操作可以向项目提交Pull Request。从修复文档、增加测试用例开始是参与开源的好方式。设计高级前端Heir目前缺乏对用户友好的高级语言前端。你可以尝试用Python绑定MLIR的Python API创建一个DSL让用户用Python函数定义计算然后自动生成MLIR代码再喂给Heir。这能极大提升易用性。走到这一步你已经从一个同态加密和编译器的旁观者变成了一个能够利用Heir这个强大工具来表述和优化同态加密电路的实践者。这条路不会轻松同态加密本身的理论深度和Heir这样的编译器工程的复杂性叠加在一起意味着你会不断遇到新的挑战。但每解决一个问题你对“如何让隐私计算真正高效可用”的理解就会加深一层。我个人最深的体会是不要试图一开始就编译一个完整的复杂模型从最简单的加法、乘法开始确保管道每一步都清晰然后像搭积木一样逐步组合。同时一定要动手去读Heir项目里的源码和测试用例那是比任何教程都更真实的学习材料。