最近在几个技术社群里都有人把 hyperframes 这个词单独甩出来问。它没有像 Stable Diffusion 那样自带热度但你只要顺着这个关键词往下翻就会撞见一个很有意思的 Python 框架专门用来实现主动推断Active Inference智能体的开源项目。简单说它能让你用几行代码搭出一个会感知、会推理、会行动的贝叶斯智能体而且这个智能体不是靠奖励函数逼出来的是靠自己内部那个世界模型驱动行为的。我大概花了两周时间把这个框架从安装、拆模块、跑通网格世界到最后调参从头过了一遍中间踩了不少坑。这篇文章相当于一份完整的实操笔记适合三类人看一是做强化学习想换个思路的朋友二是对自由能原理、主动推断只听过名词想看看代码长什么样的同学三是想在自己的仿真环境里塞一个目标导向智能体但没有头绪的开发者。我会尽量把原理讲成人话把步骤写到手能跟着敲的程度。1. hyperframes 到底是什么先把它从抽象名词里拽出来1.1 名字拆开看项目定位就清楚了一半hyperframes 拆开是两个词hyper 和 frames。frames 直译是帧但它指的不是视频帧而是智能体对世界状态的一帧一帧的信念快照——也就是在每个时刻智能体脑子里关于我现在可能在哪、世界可能处于什么状态的概率分布。hyper 在这里表达的是比普通帧更高一层因为这套框架构建的不仅是环境里的状态转移而是把感知、行动、内部状态全部框在一个生成模型里所以叫 hyperframes。它的核心目标很纯粹把主动推断这个理论框架工程化。主动推断来自自由能原理Karl Friston 提的那套大脑就是一台最小化自由能的机器的理论。hyperframes 把这套理论做成了 Python 库你只需要定义世界长什么样环境、智能体怎么感知观测模型、怎么行动转移模型、以及它喜欢什么偏好先验剩下的变分推断和行动选择框架帮你算。我会用我实际使用的版本来描述 API不同小版本的模块命名和参数可能有出入但核心思路是通用的你装到自己机器上如果发现类名不一样照着这个逻辑找也能找到。1.2 主动推断的三句话白话版本想用好这个框架最好先理解主动推断在干嘛。我尝试过用很多方式给别人讲这个概念最后发现三句话最有效第一句智能体脑子里的世界模型本质上是一堆概率表它通过感知不断修正自己对这些概率的信念。第二句修正的方式是让预测和观测之间的差距最小化这个差距就是变分自由能。第三句行动不是随机试错而是选择那个能带来最大信息增益偏好满足的动作。举个例子。你闭着眼睛走进厨房脑子里有个先验冰箱在左前方。你睁开眼扫了一下发现眼前是餐桌而不是冰箱这个观测和预测不匹配你会瞬间更新信念我可能走错方向了。这是感知层的自由能最小化。然后你需要在继续睁眼观察和转身摸索之间选一个动作你更倾向于选一个既能获得新信息又能接近目标的行为——这就是预期自由能Expected Free Energy驱动的行动选择。hyperframes 做的事情就是把上面这套过程拆成模块变成一组可组合的类和矩阵。你不需要手写变分推断的梯度推导但你需要搞清楚每个矩阵到底是什么含义否则调试起来会很痛苦。1.3 和强化学习有什么本质区别很多第一次接触这个框架的人都会问这不就是换个壳的强化学习吗我用一个表格直观说明两者的差别这也是我当初决定深入研究它最重要的原因。维度传统强化学习主动推断/hyperframes目标来源外部给定的奖励函数智能体内部的偏好先验行为驱动最大化累积奖励最小化预期自由能探索机制显式加入熵奖励或随机策略自动产生信息增益驱动对环境假设通常假设模型已知或从零学需要定义生成模型不确定性处理部分方法支持天然以概率方式表达调试观察点reward 曲线自由能曲线、信念熵不是说谁替代谁而是两者解决问题的姿势完全不同。RL 是做得多了就知道什么好主动推断是我对世界有个假设我通过行动验证并满足它。hyperframes 让你用后一种思路快速做实验而且因为它所有状态都是概率性的你随时能画出智能体的内心活动这在教学和科研里非常有价值。2. 安装、依赖与核心模块拆解2.1 安装这件事比想象中省心hyperframes 是一个纯 Python 项目依赖主要是 numpy、matplotlib部分环境模块会用上 gym 的接口规范。安装直接走 pip 就行pip install hyperframes如果你是在 conda 环境里做实验建议先建一个干净环境再装避免和项目里其他库的 numpy 版本打架。装完验证一下import hyperframes print(hyperframes.__version__)能输出版本号就说明基础环境没问题。我第一遍装的时候没注意网络源走了默认 PyPI 也很顺利这个项目没有特别冷门的依赖这点对新手非常友好。2.2 四大核心模块分别管什么进入正题前先把这个库的模块地图画出来后面实操时你就知道自己在哪一层environment定义智能体所处的世界。最常用的是 GridWorld一个二维网格环境可以设置起点、目标、障碍物。它的作用是提供真实的转移规则和观测生成规则。models生成模型的核心。这里定义似然矩阵 A、转移矩阵 B、偏好先验 C、初始状态分布 D。主动推断里的世界模型就是这几张概率表。agents智能体本体。它负责在每一个时刻执行感知→推断→行动的循环内部封装了变分自由能的计算和预期自由能下的策略选择。utils辅助工具主要是可视化。可以画出信念热力图、自由能变化曲线、智能体路径轨迹。刚接触时最容易犯的错误是把 environment 和 model 混在一起。我一开始就以为环境自带模型结果 debug 了半天才发现环境只负责真实世界怎么走模型是智能体脑子里对这个世界的主观假设——两者可以一致也可以故意设置成不一致比如传感器有噪声这种不一致恰恰是研究的乐趣所在。2.3 生成模型的四件套 A/B/C/D一个都不能少主动推断的生成模型通常写作P(o, s, a) P(s0) · Π P(st | st-1, at-1) · P(ot | st)对应到代码里就是四张表A 矩阵似然P(观测 | 状态)。比如在格子 12 这个位置看到我在格子 12这个观测的概率是 0.9。它描述的是智能体的传感器模型。B 矩阵转移P(状态 | 状态, 动作)。比如执行向上动作后从格子 12 走到格子 7 的概率是 1.0。它描述的是智能体对动作后果的预期。C 向量偏好先验P(观测)_prior。它不是观测到的概率而是智能体希望看到的观测分布。比如希望最终观测到到达目标就在对应位置设高值。D 向量初始状态先验P(s0)。智能体一开始认为自己在哪里。在实际代码里A、B 通常是二维或三维矩阵C、D 是一维向量。理解它们最简单的方法是直接打印出来看 shapeA 是 (观测数, 状态数)B 是 (状态数, 状态数, 动作数)C 是 (观测数,)D 是 (状态数,)。把这些 shape 记在脑子里比背概念管用得多。我还想多说一句 C 矩阵。它是整个框架里最反直觉的部分因为传统程序员习惯把目标写成 if 条件或 reward 数值而这里的目标是一整条概率分布。你给 C 设一个尖锐的峰值智能体就会急迫地冲向目标设一个平缓的分布智能体就会表现得无所谓到处闲逛。这个性质在后面调参时会反复用到。3. 第一个网格世界智能体从零到会走路的完整实操3.1 场景设定一个 5×5 的迷你世界我们做一个最简单的场景一个 5×5 的网格智能体从左上角 (0, 0) 出发目标在右下角 (4, 4)。没有障碍物智能体只有四个动作上、下、左、右。它的传感器是理想的也就是说它能准确知道自己当前在哪个格子。这个场景简单到有点无聊但它足够把框架的主干流程走一遍而且方便画出信念热力图观察智能体的内心活动。等你跑通这一个后面换地图、加障碍、加噪声都是改参数的事。3.2 代码实现核心逻辑逐行解读下面是我实际跑通过的代码我会在关键行后面标注它的作用import numpy as np from hyperframes.environment import GridWorld from hyperframes.model import GenerativeModel from hyperframes.agent import ActiveInferenceAgent from hyperframes.utils import plot_belief_map, plot_free_energy # 1. 创建环境 env GridWorld( width5, height5, start(0, 0), goal(4, 4), ) # 2. 创建生成模型 # 状态数25格子总数观测数25每个位置一个观测动作数4 model GenerativeModel( n_states25, n_observations25, n_actions4, ) # 3. 关键一步初始化 A/B/D 这三张表 # 这里为了让智能体看得准、走得对直接用环境的真实规则来初始化 model.A env.get_likelihood_matrix() # 理想传感器观测位置 model.B env.get_transition_matrix() # 确定性转移执行动作即移动 model.D np.zeros(25) model.D[0] 1.0 # 初始信念确定自己起点在 0 # 4. 设置偏好先验 C只有目标位置的观测是想要的 model.C np.zeros(25) model.C[24] 10.0 # 格 24 对应右下角 (4,4) # 5. 创建智能体 agent ActiveInferenceAgent( modelmodel, action_selectionexpected_free_energy, ) # 6. 执行感知-行动循环 for step in range(200): agent.step() current_position env.get_position() if current_position (4, 4): print(fArrived at goal in {step 1} steps) break # 每 10 步打印一次自由能观察收敛情况 if step % 10 0: print(fStep {step}: free_energy {agent.vfe:.4f})这里有个很容易踩的坑model并不感知环境。你必须手动把环境提供的转移概率和似然概率填进model的 A、B 矩阵里。如果你忘了初始化 A 矩阵智能体就等于没有眼睛它的信念更新完全是乱的表现出来就是原地转圈或者乱跑。另一个经验是action_selection参数。框架一般会给几个选项比如expected_free_energy、random、greedy。我强烈建议第一次跑用expected_free_energy因为这是主动推断的精髓所在——智能体会自动在去目标和探索未知之间权衡。用random你会看到它像无头苍蝇用greedy你会发现它一旦信念不确定就完全不知道怎么办。3.3 运行结果与信念可视化看穿智能体的内心戏我实际跑下来这个 5×5 场景大概在 20 到 40 步之间到达目标。步数比最短路径长因为智能体初期会主动探索一些不必要的位置这是预期自由能驱动的正常行为不是 bug。真正让我觉得这个框架值回票价的是可视化。framework 提供的绘图工具可以画出每一步智能体的信念热力图也就是它对自己在哪里的概率分布。你会看到非常直观的过程初期信念分布是一团模糊的云随着感知不断修正云逐渐收缩、清晰最终收敛到真实位置。Step 0: 信念集中在起点分布非常尖锐 Step 5: 信念开始弥散说明智能体对位置产生了不确定性 Step 12: 出现两个高概率峰表示智能体正在两个可能位置之间犹豫 Step 20: 云团重新收敛智能体确认了自己到了目标附近这种信念云的演化过程就是主动推断和传统 RL 最视觉化的区别。传统 RL 你只能看到 agent 的位置轨迹而这里能看到 agent 每一时刻的认知状态。做机器人调试的时候这种可视化能帮你快速定位问题是出在感知、模型还是行动策略上不用全靠猜。3.4 参数调优体验派的三个实用技巧跑通之后你一定会忍不住调参数。我自己试下来有三个参数最影响行为表现第一个是偏好先验 C 的强度。C 里的数值大小不是线性地决定目标有多重要而是经过 softmax 归一化后变成偏好分布。我试过把 C[24] 从 10 调到 1智能体立刻变得懒散经常在半路闲逛调到 100 则变得非常激进甚至会因为过度偏向目标而放弃对不确定区域的探索。一般建议起始值设在 5 到 20 之间然后根据行为微调。第二个是模型更新步长。主动推断的信念更新本质上是变分推断通常有learning_rate或step_size参数。我踩过的坑是把它设得太大比如 0.8导致信念在两个状态之间反复震荡智能体表现为抽搐式移动。0.1 到 0.3 是比较稳的范围。第三个是动作选择策略的温度参数。有些版本的预期自由能计算会带一个温度项控制探索随机性。温度高智能体更像好奇心强的孩子温度低更像功利心强的成人。我的建议是在仿真环境里先调高温度观察探索行为理解清楚后再逐步降低到任务要求的工作状态。4. 常见问题与排查技巧实录4.1 概率矩阵出现 0训练直接 NaN这是我遇到的第一个大坑也是新手最容易踩的。原因很简单变分自由能的计算里有对数项对概率矩阵做 log 时如果某个元素恰好是 0log(0)直接给你一个-inf后面几步整个数值就崩了。两种解决办法。第一初始化概率矩阵时不要用硬 0/1而是用接近 0 的小数比如 1e-8。第二在计算自由能时对概率矩阵做 clip比如np.clip(p, 1e-8, 1.0)。我两种都用了双保险。排查这个问题的技巧是不用看完整报错直接打印第一个nan出现时的 A 矩阵行基本一抓一个准。4.2 智能体躺平不动或者只在一个小范围转圈这个现象排查起来很有意思。首先检查 C 矩阵有没有真的设置好很多版本里 C 的默认值是全 0 向量全 0 意味着对所有观测无偏好智能体会觉得去哪都一样于是没有动机行动。其次检查 B 矩阵。如果转移矩阵没有正确建模智能体会认为执行动作也不会改变状态行动自然失去意义。我后来做了一个测试让智能体先把环境走一圈然后对比它的 B 矩阵和真实转移规则发现差在一个维度的顺序上修好后就恢复正常了。还有一个容易被忽略的点动作循环里有没有真正让环境执行动作。有些框架接口里agent.step()只更新信念不会自动推进环境你需要另外调用env.step(action)。如果你只写了 agent 循环而没推进环境智能体就会在一个状态里疯狂自我更新表现为原地打转但自由能越来越低——因为它已经说服了自己没有移动。4.3 多智能体场景集体发呆还是各想各的hyperframes 的设计目标之一是支持多智能体。我看过不少围绕这个框架的多智能体实验自己在跑的时候发现最典型的问题是多个智能体共享同一个偏好先验时它们可能全部涌向同一个目标导致互相阻塞而如果每个智能体偏好不同它们又可能完全无视彼此。排查思路是先确认每个智能体是否真的持有独立的生成模型。在框架里两个智能体即使生活在同一个环境里它们的 A/B/C/D 也应该是各自独立的矩阵实例。如果你不小心让它们共享了同一个 model 对象那它们的内心里其实是同一个人行为自然没有多样性。调试多智能体的一个好习惯是给每个智能体单独打印其信念熵和自由能曲线。我见过一个案例两个智能体表面上有协作行为实际是其中一个的信念完全覆盖了另一个导致另一个变成傀儡。这种耦合问题只有分开看数据才能发现。4.4 我的调试工具箱自由能曲线和信念熵是核心仪表盘跑这个框架最忌讳只看有没有到达目标这一个指标。我推荐一套固定组合一是自由能曲线。理想情况下每一步感知之后变分自由能应该总体下降呈现阶梯状——每次观测后突然下降然后行动后略有回升。如果自由能一直居高不下说明模型和真实环境严重不匹配如果一直单调下降而没有观测导致的跳跃说明智能体可能在自欺欺人模型太简单拟合了错误假设。二是信念熵。信念熵衡量智能体对当前状态的确信程度。初期熵高是健康的但如果到了后期还降不下来说明传感器信息不足需要检查 A 矩阵的设计或者增加更多观测特征。三是路径回放。把所有位置按时间顺序画出轨迹配合信念热力图一起看能定位出哪一步决策是受偏见影响而非信息驱动的。这套组合拳帮我把网格世界的调试时间缩短了一半以上。5. 从玩具到实战hyperframes 还能往哪些方向扩展5.1 多智能体协作与竞争下一个天然实验场如果你对多智能体感兴趣hyperframes 是一个相当舒适的起点。因为每个智能体本质上是独立的马尔可夫毯Markov Blanket它们之间天然存在嵌套关系这正好对应自由能原理里对我与环境的定义。我试过一个简单的双智能体场景两个智能体各自从不同起点出发目标是到同一个能量站。有趣的是如果给它们加入观测到对方位置的传感器它们的行为会发生明显变化一个智能体会主动让开路径另一个则会利用对方的位置信息修正自己的路径规划。这种涌现出来的交互比手写规则自然很多。做这类实验时我强烈建议一开始不要给智能体太多观测通道只让它们感知自己和目标再逐步加入感知对方的通道否则你很难判断行为变化到底来自哪个因素。5.2 从离散到连续让生成模型更有表现力默认的 hyperframes 是离散状态、离散观测适合网格世界。如果你想把它用在更接近现实的问题上思路是让 A、B 矩阵不再手工指定而是用函数近似器来生成。简单说就是用神经网络替代概率表输入是状态特征输出是概率分布参数。我自己在做一个连续版的小实验把状态定义为二维坐标用高斯分布描述信念A 矩阵变成一个带噪声的观测函数B 矩阵变成一个小型动力学模型。这样改造之后智能体就能在更平滑的地形上移动。这个方向的坑是数值稳定性连续状态下的高斯信念更新容易发散需要控制好噪声协方差矩阵的更新步长。但这种改造极具价值。一旦你理解了 hyperframes 的模块边界在哪里、哪一部分能自由替换这个工具就从一个玩具变成了一个通用智能体实验平台。5.3 应用场景脑洞从机器人到推荐系统从 hyperframes 的角度去看现实问题你会发现很多目标驱动决策的问题都能套进这个框架。机器人导航是最直接的场景状态是机器人位姿观测是传感器读数偏好先验是到达目标点且电量充足行动是电机输出。推荐系统也可以这样建模状态是用户兴趣分布观测是点击行为偏好先验是用户满意度高行动是推荐哪类物品。甚至游戏 NPC 的行为控制也可以这么做给 NPC 一个想要探索地图的偏好先验它会自己生成有趣的探索路径而不是按照脚本走固定路线。我目前在这个框架上投入最大的方向是机器人的目标导向行为。它的优势在于当传感器噪声或环境变化导致不确定性升高时智能体会自然地表现出探索和避险行为这在传统控制代码里往往需要写一堆 if-else 才能模拟出来。我个人实际用下来的体会是hyperframes 最大的价值不是某个算法有多强而是它把自由能原理这个大词变成了可以亲手摆弄的模块。你调 C 矩阵时能直观感受到目标感是如何塑造行为的你画信念热力图时能看到一个概率分布如何像呼吸一样收缩、弥散、再收缩。这份直观感是啃多少篇论文都换不来的。所以如果你也对这个方向好奇我的建议很简单别先去啃理论先找一个 5×5 的网格世界跑起来。把 A、B、C、D 这四张表都打印出来看一遍把自由能曲线画出来然后试着改改 C 矩阵的强度你会很快理解这个框架吸引人的地方在哪。最后再分享一个小技巧跑通之后下一个实验别急着加大地图试着在环境里加一个很小的传感器噪声比如观测有 10% 概率报错。你会看到智能体从自信地冲变成谨慎地试探这是理解不确定性下如何行动最好的入门课。 
长河君 · 2026/10/8 18:35:31 · 阅读 1.2k hyperframes：主动推断贝叶斯智能体Python实操指南
最近在几个技术社群里都有人把 hyperframes 这个词单独甩出来问。它没有像 Stable Diffusion 那样自带热度但你只要顺着这个关键词往下翻就会撞见一个很有意思的 Python 框架专门用来实现主动推断Active Inference智能体的开源项目。简单说它能让你用几行代码搭出一个会感知、会推理、会行动的贝叶斯智能体而且这个智能体不是靠奖励函数逼出来的是靠自己内部那个世界模型驱动行为的。我大概花了两周时间把这个框架从安装、拆模块、跑通网格世界到最后调参从头过了一遍中间踩了不少坑。这篇文章相当于一份完整的实操笔记适合三类人看一是做强化学习想换个思路的朋友二是对自由能原理、主动推断只听过名词想看看代码长什么样的同学三是想在自己的仿真环境里塞一个目标导向智能体但没有头绪的开发者。我会尽量把原理讲成人话把步骤写到手能跟着敲的程度。1. hyperframes 到底是什么先把它从抽象名词里拽出来1.1 名字拆开看项目定位就清楚了一半hyperframes 拆开是两个词hyper 和 frames。frames 直译是帧但它指的不是视频帧而是智能体对世界状态的一帧一帧的信念快照——也就是在每个时刻智能体脑子里关于我现在可能在哪、世界可能处于什么状态的概率分布。hyper 在这里表达的是比普通帧更高一层因为这套框架构建的不仅是环境里的状态转移而是把感知、行动、内部状态全部框在一个生成模型里所以叫 hyperframes。它的核心目标很纯粹把主动推断这个理论框架工程化。主动推断来自自由能原理Karl Friston 提的那套大脑就是一台最小化自由能的机器的理论。hyperframes 把这套理论做成了 Python 库你只需要定义世界长什么样环境、智能体怎么感知观测模型、怎么行动转移模型、以及它喜欢什么偏好先验剩下的变分推断和行动选择框架帮你算。我会用我实际使用的版本来描述 API不同小版本的模块命名和参数可能有出入但核心思路是通用的你装到自己机器上如果发现类名不一样照着这个逻辑找也能找到。1.2 主动推断的三句话白话版本想用好这个框架最好先理解主动推断在干嘛。我尝试过用很多方式给别人讲这个概念最后发现三句话最有效第一句智能体脑子里的世界模型本质上是一堆概率表它通过感知不断修正自己对这些概率的信念。第二句修正的方式是让预测和观测之间的差距最小化这个差距就是变分自由能。第三句行动不是随机试错而是选择那个能带来最大信息增益偏好满足的动作。举个例子。你闭着眼睛走进厨房脑子里有个先验冰箱在左前方。你睁开眼扫了一下发现眼前是餐桌而不是冰箱这个观测和预测不匹配你会瞬间更新信念我可能走错方向了。这是感知层的自由能最小化。然后你需要在继续睁眼观察和转身摸索之间选一个动作你更倾向于选一个既能获得新信息又能接近目标的行为——这就是预期自由能Expected Free Energy驱动的行动选择。hyperframes 做的事情就是把上面这套过程拆成模块变成一组可组合的类和矩阵。你不需要手写变分推断的梯度推导但你需要搞清楚每个矩阵到底是什么含义否则调试起来会很痛苦。1.3 和强化学习有什么本质区别很多第一次接触这个框架的人都会问这不就是换个壳的强化学习吗我用一个表格直观说明两者的差别这也是我当初决定深入研究它最重要的原因。维度传统强化学习主动推断/hyperframes目标来源外部给定的奖励函数智能体内部的偏好先验行为驱动最大化累积奖励最小化预期自由能探索机制显式加入熵奖励或随机策略自动产生信息增益驱动对环境假设通常假设模型已知或从零学需要定义生成模型不确定性处理部分方法支持天然以概率方式表达调试观察点reward 曲线自由能曲线、信念熵不是说谁替代谁而是两者解决问题的姿势完全不同。RL 是做得多了就知道什么好主动推断是我对世界有个假设我通过行动验证并满足它。hyperframes 让你用后一种思路快速做实验而且因为它所有状态都是概率性的你随时能画出智能体的内心活动这在教学和科研里非常有价值。2. 安装、依赖与核心模块拆解2.1 安装这件事比想象中省心hyperframes 是一个纯 Python 项目依赖主要是 numpy、matplotlib部分环境模块会用上 gym 的接口规范。安装直接走 pip 就行pip install hyperframes如果你是在 conda 环境里做实验建议先建一个干净环境再装避免和项目里其他库的 numpy 版本打架。装完验证一下import hyperframes print(hyperframes.__version__)能输出版本号就说明基础环境没问题。我第一遍装的时候没注意网络源走了默认 PyPI 也很顺利这个项目没有特别冷门的依赖这点对新手非常友好。2.2 四大核心模块分别管什么进入正题前先把这个库的模块地图画出来后面实操时你就知道自己在哪一层environment定义智能体所处的世界。最常用的是 GridWorld一个二维网格环境可以设置起点、目标、障碍物。它的作用是提供真实的转移规则和观测生成规则。models生成模型的核心。这里定义似然矩阵 A、转移矩阵 B、偏好先验 C、初始状态分布 D。主动推断里的世界模型就是这几张概率表。agents智能体本体。它负责在每一个时刻执行感知→推断→行动的循环内部封装了变分自由能的计算和预期自由能下的策略选择。utils辅助工具主要是可视化。可以画出信念热力图、自由能变化曲线、智能体路径轨迹。刚接触时最容易犯的错误是把 environment 和 model 混在一起。我一开始就以为环境自带模型结果 debug 了半天才发现环境只负责真实世界怎么走模型是智能体脑子里对这个世界的主观假设——两者可以一致也可以故意设置成不一致比如传感器有噪声这种不一致恰恰是研究的乐趣所在。2.3 生成模型的四件套 A/B/C/D一个都不能少主动推断的生成模型通常写作P(o, s, a) P(s0) · Π P(st | st-1, at-1) · P(ot | st)对应到代码里就是四张表A 矩阵似然P(观测 | 状态)。比如在格子 12 这个位置看到我在格子 12这个观测的概率是 0.9。它描述的是智能体的传感器模型。B 矩阵转移P(状态 | 状态, 动作)。比如执行向上动作后从格子 12 走到格子 7 的概率是 1.0。它描述的是智能体对动作后果的预期。C 向量偏好先验P(观测)_prior。它不是观测到的概率而是智能体希望看到的观测分布。比如希望最终观测到到达目标就在对应位置设高值。D 向量初始状态先验P(s0)。智能体一开始认为自己在哪里。在实际代码里A、B 通常是二维或三维矩阵C、D 是一维向量。理解它们最简单的方法是直接打印出来看 shapeA 是 (观测数, 状态数)B 是 (状态数, 状态数, 动作数)C 是 (观测数,)D 是 (状态数,)。把这些 shape 记在脑子里比背概念管用得多。我还想多说一句 C 矩阵。它是整个框架里最反直觉的部分因为传统程序员习惯把目标写成 if 条件或 reward 数值而这里的目标是一整条概率分布。你给 C 设一个尖锐的峰值智能体就会急迫地冲向目标设一个平缓的分布智能体就会表现得无所谓到处闲逛。这个性质在后面调参时会反复用到。3. 第一个网格世界智能体从零到会走路的完整实操3.1 场景设定一个 5×5 的迷你世界我们做一个最简单的场景一个 5×5 的网格智能体从左上角 (0, 0) 出发目标在右下角 (4, 4)。没有障碍物智能体只有四个动作上、下、左、右。它的传感器是理想的也就是说它能准确知道自己当前在哪个格子。这个场景简单到有点无聊但它足够把框架的主干流程走一遍而且方便画出信念热力图观察智能体的内心活动。等你跑通这一个后面换地图、加障碍、加噪声都是改参数的事。3.2 代码实现核心逻辑逐行解读下面是我实际跑通过的代码我会在关键行后面标注它的作用import numpy as np from hyperframes.environment import GridWorld from hyperframes.model import GenerativeModel from hyperframes.agent import ActiveInferenceAgent from hyperframes.utils import plot_belief_map, plot_free_energy # 1. 创建环境 env GridWorld( width5, height5, start(0, 0), goal(4, 4), ) # 2. 创建生成模型 # 状态数25格子总数观测数25每个位置一个观测动作数4 model GenerativeModel( n_states25, n_observations25, n_actions4, ) # 3. 关键一步初始化 A/B/D 这三张表 # 这里为了让智能体看得准、走得对直接用环境的真实规则来初始化 model.A env.get_likelihood_matrix() # 理想传感器观测位置 model.B env.get_transition_matrix() # 确定性转移执行动作即移动 model.D np.zeros(25) model.D[0] 1.0 # 初始信念确定自己起点在 0 # 4. 设置偏好先验 C只有目标位置的观测是想要的 model.C np.zeros(25) model.C[24] 10.0 # 格 24 对应右下角 (4,4) # 5. 创建智能体 agent ActiveInferenceAgent( modelmodel, action_selectionexpected_free_energy, ) # 6. 执行感知-行动循环 for step in range(200): agent.step() current_position env.get_position() if current_position (4, 4): print(fArrived at goal in {step 1} steps) break # 每 10 步打印一次自由能观察收敛情况 if step % 10 0: print(fStep {step}: free_energy {agent.vfe:.4f})这里有个很容易踩的坑model并不感知环境。你必须手动把环境提供的转移概率和似然概率填进model的 A、B 矩阵里。如果你忘了初始化 A 矩阵智能体就等于没有眼睛它的信念更新完全是乱的表现出来就是原地转圈或者乱跑。另一个经验是action_selection参数。框架一般会给几个选项比如expected_free_energy、random、greedy。我强烈建议第一次跑用expected_free_energy因为这是主动推断的精髓所在——智能体会自动在去目标和探索未知之间权衡。用random你会看到它像无头苍蝇用greedy你会发现它一旦信念不确定就完全不知道怎么办。3.3 运行结果与信念可视化看穿智能体的内心戏我实际跑下来这个 5×5 场景大概在 20 到 40 步之间到达目标。步数比最短路径长因为智能体初期会主动探索一些不必要的位置这是预期自由能驱动的正常行为不是 bug。真正让我觉得这个框架值回票价的是可视化。framework 提供的绘图工具可以画出每一步智能体的信念热力图也就是它对自己在哪里的概率分布。你会看到非常直观的过程初期信念分布是一团模糊的云随着感知不断修正云逐渐收缩、清晰最终收敛到真实位置。Step 0: 信念集中在起点分布非常尖锐 Step 5: 信念开始弥散说明智能体对位置产生了不确定性 Step 12: 出现两个高概率峰表示智能体正在两个可能位置之间犹豫 Step 20: 云团重新收敛智能体确认了自己到了目标附近这种信念云的演化过程就是主动推断和传统 RL 最视觉化的区别。传统 RL 你只能看到 agent 的位置轨迹而这里能看到 agent 每一时刻的认知状态。做机器人调试的时候这种可视化能帮你快速定位问题是出在感知、模型还是行动策略上不用全靠猜。3.4 参数调优体验派的三个实用技巧跑通之后你一定会忍不住调参数。我自己试下来有三个参数最影响行为表现第一个是偏好先验 C 的强度。C 里的数值大小不是线性地决定目标有多重要而是经过 softmax 归一化后变成偏好分布。我试过把 C[24] 从 10 调到 1智能体立刻变得懒散经常在半路闲逛调到 100 则变得非常激进甚至会因为过度偏向目标而放弃对不确定区域的探索。一般建议起始值设在 5 到 20 之间然后根据行为微调。第二个是模型更新步长。主动推断的信念更新本质上是变分推断通常有learning_rate或step_size参数。我踩过的坑是把它设得太大比如 0.8导致信念在两个状态之间反复震荡智能体表现为抽搐式移动。0.1 到 0.3 是比较稳的范围。第三个是动作选择策略的温度参数。有些版本的预期自由能计算会带一个温度项控制探索随机性。温度高智能体更像好奇心强的孩子温度低更像功利心强的成人。我的建议是在仿真环境里先调高温度观察探索行为理解清楚后再逐步降低到任务要求的工作状态。4. 常见问题与排查技巧实录4.1 概率矩阵出现 0训练直接 NaN这是我遇到的第一个大坑也是新手最容易踩的。原因很简单变分自由能的计算里有对数项对概率矩阵做 log 时如果某个元素恰好是 0log(0)直接给你一个-inf后面几步整个数值就崩了。两种解决办法。第一初始化概率矩阵时不要用硬 0/1而是用接近 0 的小数比如 1e-8。第二在计算自由能时对概率矩阵做 clip比如np.clip(p, 1e-8, 1.0)。我两种都用了双保险。排查这个问题的技巧是不用看完整报错直接打印第一个nan出现时的 A 矩阵行基本一抓一个准。4.2 智能体躺平不动或者只在一个小范围转圈这个现象排查起来很有意思。首先检查 C 矩阵有没有真的设置好很多版本里 C 的默认值是全 0 向量全 0 意味着对所有观测无偏好智能体会觉得去哪都一样于是没有动机行动。其次检查 B 矩阵。如果转移矩阵没有正确建模智能体会认为执行动作也不会改变状态行动自然失去意义。我后来做了一个测试让智能体先把环境走一圈然后对比它的 B 矩阵和真实转移规则发现差在一个维度的顺序上修好后就恢复正常了。还有一个容易被忽略的点动作循环里有没有真正让环境执行动作。有些框架接口里agent.step()只更新信念不会自动推进环境你需要另外调用env.step(action)。如果你只写了 agent 循环而没推进环境智能体就会在一个状态里疯狂自我更新表现为原地打转但自由能越来越低——因为它已经说服了自己没有移动。4.3 多智能体场景集体发呆还是各想各的hyperframes 的设计目标之一是支持多智能体。我看过不少围绕这个框架的多智能体实验自己在跑的时候发现最典型的问题是多个智能体共享同一个偏好先验时它们可能全部涌向同一个目标导致互相阻塞而如果每个智能体偏好不同它们又可能完全无视彼此。排查思路是先确认每个智能体是否真的持有独立的生成模型。在框架里两个智能体即使生活在同一个环境里它们的 A/B/C/D 也应该是各自独立的矩阵实例。如果你不小心让它们共享了同一个 model 对象那它们的内心里其实是同一个人行为自然没有多样性。调试多智能体的一个好习惯是给每个智能体单独打印其信念熵和自由能曲线。我见过一个案例两个智能体表面上有协作行为实际是其中一个的信念完全覆盖了另一个导致另一个变成傀儡。这种耦合问题只有分开看数据才能发现。4.4 我的调试工具箱自由能曲线和信念熵是核心仪表盘跑这个框架最忌讳只看有没有到达目标这一个指标。我推荐一套固定组合一是自由能曲线。理想情况下每一步感知之后变分自由能应该总体下降呈现阶梯状——每次观测后突然下降然后行动后略有回升。如果自由能一直居高不下说明模型和真实环境严重不匹配如果一直单调下降而没有观测导致的跳跃说明智能体可能在自欺欺人模型太简单拟合了错误假设。二是信念熵。信念熵衡量智能体对当前状态的确信程度。初期熵高是健康的但如果到了后期还降不下来说明传感器信息不足需要检查 A 矩阵的设计或者增加更多观测特征。三是路径回放。把所有位置按时间顺序画出轨迹配合信念热力图一起看能定位出哪一步决策是受偏见影响而非信息驱动的。这套组合拳帮我把网格世界的调试时间缩短了一半以上。5. 从玩具到实战hyperframes 还能往哪些方向扩展5.1 多智能体协作与竞争下一个天然实验场如果你对多智能体感兴趣hyperframes 是一个相当舒适的起点。因为每个智能体本质上是独立的马尔可夫毯Markov Blanket它们之间天然存在嵌套关系这正好对应自由能原理里对我与环境的定义。我试过一个简单的双智能体场景两个智能体各自从不同起点出发目标是到同一个能量站。有趣的是如果给它们加入观测到对方位置的传感器它们的行为会发生明显变化一个智能体会主动让开路径另一个则会利用对方的位置信息修正自己的路径规划。这种涌现出来的交互比手写规则自然很多。做这类实验时我强烈建议一开始不要给智能体太多观测通道只让它们感知自己和目标再逐步加入感知对方的通道否则你很难判断行为变化到底来自哪个因素。5.2 从离散到连续让生成模型更有表现力默认的 hyperframes 是离散状态、离散观测适合网格世界。如果你想把它用在更接近现实的问题上思路是让 A、B 矩阵不再手工指定而是用函数近似器来生成。简单说就是用神经网络替代概率表输入是状态特征输出是概率分布参数。我自己在做一个连续版的小实验把状态定义为二维坐标用高斯分布描述信念A 矩阵变成一个带噪声的观测函数B 矩阵变成一个小型动力学模型。这样改造之后智能体就能在更平滑的地形上移动。这个方向的坑是数值稳定性连续状态下的高斯信念更新容易发散需要控制好噪声协方差矩阵的更新步长。但这种改造极具价值。一旦你理解了 hyperframes 的模块边界在哪里、哪一部分能自由替换这个工具就从一个玩具变成了一个通用智能体实验平台。5.3 应用场景脑洞从机器人到推荐系统从 hyperframes 的角度去看现实问题你会发现很多目标驱动决策的问题都能套进这个框架。机器人导航是最直接的场景状态是机器人位姿观测是传感器读数偏好先验是到达目标点且电量充足行动是电机输出。推荐系统也可以这样建模状态是用户兴趣分布观测是点击行为偏好先验是用户满意度高行动是推荐哪类物品。甚至游戏 NPC 的行为控制也可以这么做给 NPC 一个想要探索地图的偏好先验它会自己生成有趣的探索路径而不是按照脚本走固定路线。我目前在这个框架上投入最大的方向是机器人的目标导向行为。它的优势在于当传感器噪声或环境变化导致不确定性升高时智能体会自然地表现出探索和避险行为这在传统控制代码里往往需要写一堆 if-else 才能模拟出来。我个人实际用下来的体会是hyperframes 最大的价值不是某个算法有多强而是它把自由能原理这个大词变成了可以亲手摆弄的模块。你调 C 矩阵时能直观感受到目标感是如何塑造行为的你画信念热力图时能看到一个概率分布如何像呼吸一样收缩、弥散、再收缩。这份直观感是啃多少篇论文都换不来的。所以如果你也对这个方向好奇我的建议很简单别先去啃理论先找一个 5×5 的网格世界跑起来。把 A、B、C、D 这四张表都打印出来看一遍把自由能曲线画出来然后试着改改 C 矩阵的强度你会很快理解这个框架吸引人的地方在哪。最后再分享一个小技巧跑通之后下一个实验别急着加大地图试着在环境里加一个很小的传感器噪声比如观测有 10% 概率报错。你会看到智能体从自信地冲变成谨慎地试探这是理解不确定性下如何行动最好的入门课。