经常有朋友问我一个特别拧巴的问题同一个大模型、同一段提示词为什么多跑两次结果就不一样还有人问我想让大模型自动写代码、改文件、跑测试是不是接个 API 就行这两个问题的答案其实都藏在大模型打分与采样原理里。大模型内部要先给每个候选内容“打分”再从分数分布里“采样”出最终结果而像 Pi Agent 这类智能体本质上就是把这些底层的打分离散化、把采样策略应用到一个可循环执行的任务流里。搞懂这两件事你就能解释很多“玄学”现象也能知道怎么配置一个稳定的 AI 编程助手。这篇我按自己实际使用的经验来写不堆公式吓人尽量用“这个词怎么影响你看到的结果”来讲。适合三类人想理解大模型 API 参数的人、做智能体应用开发的工程师以及正在对比 Pi Agent、OpenCode、Codex 到底哪个好用的工具党。1. 大模型“打分”到底意味着什么1.1 词元打分每一步都在做选择题很多人以为大模型是在“造句”其实不是。它更像一个超级接龙选手每次只预测下一个词元token是什么。为了预测这个“下一个词元”模型会给词表里的几万个候选词元分别算出一个分数这个分数在技术上叫 logits。logits 本身是未归一化的原始分数可以是正的也可以是负的数值大小代表模型对这个候选的“倾向程度”。光有原始分数还不行要变成能用的概率得经过一层 softmax把这批分数映射成 0 到 1 之间、且加起来等于 1 的概率分布。最后模型再从分布里挑一个词元作为输出。这整个过程就是大模型打分的核心。你可能听过“奖励模型”“打分模型”这种说法那是另外一层意思但底层本质也是类似的模型要学习如何给候选输出分配分数只不过一个用在解码环节一个用于训练和对齐。日常调试模型表现时如果你发现某些回答特别“犟”、怎么改提示词都不变那多半是某几个候选词元的分数差距太大softmax 之后几乎把概率全压在了同一个词上采样空间被压没了。1.2 用大模型当裁判另一种“打分”除了内部给词元打分现在流行把大模型本身当“评分员”用。做法很简单让模型对一段文本、一段代码或一个回答按标准打分再给点理由。这就是业内常说的 LLM-as-a-judge。这个用法在 Agent 场景里尤其重要。比如 Pi Agent 写完一段代码后可以用另一个模型或同一模型扮演审查者输出“这段代码是否通过检查分数 0-10问题点有哪些”。这比人肉 review 快得多但坑也很明显同一个模型既当运动员又当裁判容易对自己的输出有偏爱换个裁判模型分数可能就差很多。我在实战里的做法是让打分的输出固定为 JSON 结构至少要包含“score”和“reason”两个字段否则后续逻辑没法解析。打分 prompt 也要给参考标准否则模型容易“唯美是从”什么问题都打高分。最好是再做个一致性校验同一个问题问两次分数差太大的就默认无效。注意大模型打分是“相对排序”的好手不是“绝对度量”的尺子用它做质量筛选没问题想拿它当精确仪器用那是找错了工具。2. 采样原理为什么同一个模型会给出不同答案2.1 温度、Top-k、Top-p三个参数到底在调什么既然模型能给出概率分布接下来就是从分布里“选一个词元”。如果每次都是挑最大概率那个输出就固定了这叫贪婪解码后面细说。真正让模型有多样性的是采样sampling。你可以把采样想成抽奖概率大的词元中奖率高但概率小的偶尔也能冒出来。控制抽奖行为的有三个常用参数。温度temperature是最直观的。它影响 softmax 的“陡峭程度”温度越低高分数词元和低分数词元的差距被拉得越大模型越保守温度越高分布越平坦低概率词元也有机会被选到。温度调到 0 时分布变得极其尖锐几乎等同于每次选最大的那个词元。图表上你看到的所谓“创造性”本质就是温度把概率抹平了而已。Top-k 是只保留概率最高的 k 个词元当候选其余的全部归零。这种方式简单粗暴k 设太大时低概率垃圾也会混进来k 设太小时内容容易单调。Top-p 又叫核采样做法是先按概率从高到低排列候选再从高处开始累计直到累计概率超过 p 才把后面的词元裁掉。它比 top-k 聪明因为候选数量是动态的分布集中时候选少分布分散时候选多。实战里的常见组合是 temperature 0.7、top_p 0.9这是很多开源模型的默认值适合一般对话生成。要是做代码生成、Agent 决策这类需要稳定性的任务我一般会把温度压到 0.2-0.4再把 top_p 放到 0.8 左右。你可能会看到某个 API 只支持 temperature不支持 top_p那是因为厂家在服务端帮你固定了采样配置。2.2 贪婪解码、束搜索与核心采样的取舍开头说的“输出完全一样”的情况其实就是两次都相当于做了贪婪解码。贪婪解码每一步都选最大概率的词元速度最快结果稳定。但它有个毛病局部最优不等于全局最优。某一步选了个高概率词后面可能把整个句子带沟里去越说越复读机。代码生成里尤其明显容易生成重复的函数名、死循环结构。束搜索beam search则是保留多条候选序列每一步都维护 top-B 条路径最后选整体概率最高的那条。这在翻译类任务里是主力因为它能照顾到全局连贯性。但代价是计算量大而且束宽设太大时反而容易生成过于“顺滑”的废话。现在很多对话模型和 Agent 都不爱用束搜索因为对话本身就该有多样性束搜索反而把这种多样性抹掉了。还有一类进阶采样方法比如典型采样typical sampling、对比搜索contrastive search。典型采样根据“信息量是否典型”来过滤词元可以缓解模型胡编乱造对比搜索在生成时同时考虑与上文的相似度和惩罚重复刷出更连贯的文本。普通用户不需要抠这些细节但如果你在搭流式输出、做推理加速值得去了解一下效果差异还挺明显。2.3 接受—拒绝采样理论优雅落地要谨慎搜索词里频繁出现“接受拒绝采样”这在数理统计里也叫 accept-reject sampling是一种生成目标分布的通用方法。核心思路是如果你没法直接从复杂分布采样就找一个容易采样的建议分布先采一个样本再用一个接受概率决定留不留它。留下的样本近似服从目标分布。这和 LLM 有什么关系关系在于生成式模型经常想从某些复杂约束下的概率分布里采样但没法直接算。比如你希望输出“既符合语法又包含指定知识点”可以把这些要求写成打分函数先生成一批候选再用打分函数过滤。符合要求的留下不符合的丢掉这就是拒绝采样的思想。现在很多带验证器的推理方法用的就是这条路线让模型多生成几次再用打分器筛选而不是赌一次运气。实际落地时注意三点一是生成批次要够大不然过滤完没得剩二是过滤器质量要靠谱如果过滤器本身也有误差最后的结果一样漂三是延迟和成本要可控我见过最夸张的一次为了筛一篇小短文生成了二十多次候选最后效果也就比直接生成好一点点性价比很低。把它当作兜底方案用别当作默认方案。3. Pi Agent 核心原理拆解它是怎么自己干活的3.1 Agent 循环感知、规划、行动、观察Pi Agent 本质是个编码智能体不是单纯的聊天应用。普通聊天是“你问一句模型答一句”Agent 则多了一个工具调用的闭环。Pi Agent 的主体循环可以简化成四步读取当前任务和上下文让大模型规划下一步动作执行这个动作可能是执行终端命令、读写文件、搜索代码库再把执行结果返回给模型继续判断。这个循环有一个很重要的设计点模型在每次迭代时输出的不再是普通文本而是结构化的动作指令。我接触过的版本里Pi Agent 会让模型在预设的动作集合里选一种比如“查看文件内容”“执行某个测试命令”“修改某个文件的某一段”然后由外部代码去执行执行结果作为新的观察喂回模型。这样做的好处是大模型的幻觉不会直接落到文件系统里所有写操作都经过了一层“审批和校验”。为什么说它依赖打分与采样因为每次“选什么动作”本质上就是从模型对多个候选动作的概率分布里采样。如果你把温度调太高同一个任务它会一会儿想改这个文件、一会儿想跑别的命令路径非常发散调太低它可能反复尝试同一种无效方案陷在死局里出不来。所以 Agent 场景下的采样参数其实是在“探索”和“稳定”之间找平衡点。我的经验是设计代码任务的 Agent让它在主流程上偏向低温度但可以在生成具体代码内容时稍微提高一点温度这样既稳定又不至于写得太死板。3.2 技能系统把经验变成可复用的指令包Pi Agent 有“技能”Skill的概念。这和我之前用过的 Claude Code 技能类似把某个领域的专业流程、常用命令、注意事项打包成一个结构化指令模型在遇到对应任务时主动调用。举个例子我自己会给 Pi Agent 配一个“Python 测试技能”。技能内容大致是先看项目根目录有没有 pytest.ini 或 pyproject.toml确定测试框架优先运行指定测试用例失败时先看报错堆栈再决定是修代码还是补依赖。这么做的目的是把“老师傅的经验”直接塞给模型免得它每次从零摸索。技能系统的核心难点不是写文档而是拆任务。大模型擅长处理小步骤不擅长一口吞下几百行需求。所以我在技能里会写明“子任务划分粒度”比如“不要一次性修改超过三个文件”“每次改完就运行对应测试再继续”。这些约束编码成技能后Pi Agent 的稳定性会明显上升。和纯依赖系统提示词相比技能的优势在于可复用和可编排。同一个技能可以跨项目使用也可以被不同项目复用。我建议把那些你反复在项目里做的事情沉淀成技能比如“项目初始化”“数据库迁移”“lint 修复”。这些都是相对标准化的流程模型只要按技能一步步走出错的概率就会低很多。3.3 上下文管理Agent 的记忆其实是稀缺资源Agent 跑起来最常见的崩溃原因不是模型变笨而是上下文被塞爆了。Pi Agent 的工作模式决定了它会把大量工具执行结果塞回模型上下文里。如果操作的文件很大或测试输出特别长上下文很快就到窗口上限。真正的核心原理是“分层记忆”。Pi Agent 不会把所有历史一字不差地交给模型而是会做一些裁剪把早期探索过程压缩成摘要只保留当前任务相关的文件路径和结论。这有点像我记笔记重点记结论过程能一笔带过就一笔带过。你在配置 Agent 时也能看到它对“上下文预算”的控制参数比如单次工具输出的最大长度、历史消息保留量。对这部分的建议不要吝啬给 Agent 规划子任务宁可多拆几步也不要让某一步的输出过长。尤其在跑大型项目时先用搜索类工具定位相关文件再精确读取局部内容比直接把整个文件丢进去要省太多 token。4. 让 Pi Agent 跑起来安装、配置与一个完整实战4.1 环境准备与安装先用一段话讲清楚大环境Pi Agent 对运行环境的要求并不苛刻主流开发机都能跑。基本前提是有个较新的 Node.js 运行时、装了 Git、能访问你要用的模型服务。安装方式根据发布形式不同常见的是走 npm 全局安装装完会有一个命令行工具入口。我这边安装完第一件事是看版本号顺便跑一下帮助命令确认工具能正常唤起。作者在这里提醒一句这类 Agent 工具迭代很快安装命令和配置文件格式经常变最稳妥的方式是打开官方文档按当前版本的说明来。网上教程很容易过期包括我这篇里的命令也只代表我写稿时用的版本。4.2 配置模型提供商与关键参数Pi Agent 本身不内置模型它需要对接一个大模型后端。最常见的两种方式一种是配置大型模型厂商的 API Key用 OpenAI 兼容的接口地址另一种是接本地模型比如通过 Ollama 启动一个本地模型再把接口地址指到 localhost。本地模型的好处是隐私好、不花钱但长上下文处理能力和代码理解能力普遍不如商用模型跑复杂 Agent 任务容易“带不动”。配置时重点看三个东西模型名和接口地址必须填对否则所有任务都会报连接错误。主模型/快速模型拆分很多 Agent 允许设置一个能力强的“主模型”负责复杂推理再配一个便宜的“快速模型”负责简单任务比如生成提交信息、做文本摘要。合理拆分能省不少成本。采样参数前面讲的 temperature、top_p 在这里就能直接配置。生产环境任务我一般设到 temperature 0.2-0.3探索型任务可以调到 0.6。还有一个很容易被忽略但非常关键的配置权限管控。Agent 要执行命令但并不是所有命令都应该被允许。你可以配置允许执行的命令白名单、禁止执行的命令黑名单或者让关键操作先征求你的确认。我之前吃过亏没配权限就让它跑测试结果 Agent 顺手执行了一个会修改全局依赖的命令折腾了半天才恢复。权限这种东西配得越细越省心。4.3 实战演示让 Pi Agent 完成一次真实的编码任务我挑一个最常见的实战场景给你完整走一遍。任务背景一个 Node.js 项目里有一个函数用来做金额格式化结果在小数位处理上有 bug需要修复并跑通测试。我给 Pi Agent 的原始指令大概是“定位金额格式化相关函数修复精度问题补充异常用例运行测试直到全部通过”。第一步Agent 会先列出项目目录搜索关键词“format”“amount”“money”之类定位候选文件。这个过程就是模型在“打分”它要根据文件路径、函数名为哪些文件最可能是目标打分再选分数最高的那个去读。第二步读取候选文件后它会找到那个格式化函数分析精度问题的来源。如果它暂时看不出问题还会去读相关的测试文件通过测试用例反推预期行为。这里能明显看到采样参数的影响如果温度太高它可能同时产生好几个修改思路但谁也不深入温度太低它可能死死咬住最初的猜测不放。第三步Agent 会直接改文件然后运行测试。如果测试没过它会把失败信息作为新观察喂回模型再次进入规划循环。我看过它的日志前两次修的方向都是补 round 操作后来测试失败提示小数边界有问题它才改成用整数运算来避免浮点误差。整个过程走了大概六轮耗时两分钟出头。第四步测试全绿之后Agent 会整理改动文件列表和测试结果给我并建议下一步动作。到这里任务闭环就完成了。这个例子看着不复杂但内部其实经历了“候选筛选 行动序列采样 测试反馈再决策”的完整 Agent 循环。你配置的模型能力越强采样参数越贴合场景这个循环收敛得就越快。5. 实践中的坑与排查清单5.1 高频故障与排查路线我用 Pi Agent 跑了几个真实项目后整理了一份高频故障速查表你在自己实践里大概率也会撞上。卡在循环里反复执行同一条命令 大概率是前一步执行的输出没有产生有效新信息模型只能重复试探。先检查是不是命令本身超时或静默失败再考虑把任务拆得更细。另一个原因是温度太低模型死守同一个路径。适当提高温度或者手动打断在反馈里纠正方向。改的文件不对或改完引入新问题 这是典型的“定位不准”而不是“生成不准”。让 Agent 在动手前先输出“影响分析和修改计划”你确认之后再执行。很多 Agent 都支持这个确认流程不要嫌麻烦。上下文爆掉导致行为异常 观察是否在长输出、大文件后开始出现不相关的动作。缓解手段包括让工具只输出文件的关键片段、限制测试输出的行数、定期用摘要替代历史消息。如果 Agent 支持记忆压缩配置调高压缩阈值。模型返回格式偶尔不合法 工具调用依赖结构化输出偶尔模型会给出残缺的 JSON 或者字段名不对导致解析失败。这类错误通常是外部的可以设置自动重试或者临时换成能力更强的模型来处理工具调用。5.2 采样参数与 Agent 稳定性的实战建议先把结论放在前面如果你希望 Pi Agent 干活足够“稳”temperature 和 top_p 的推荐区间是 0.2-0.4 和 0.7-0.9。这和一个聊天助手动辄用 0.8-1.0 的配置很不一样原因在于 Agent 的任务是执行多步操作中途每多一次采样波动就会多一分路径偏差。写文案可以放飞但改代码和跑命令必须收敛。我也试过把温度调到 0结果同样不理想。问题在于Agent 的每一步都可能遇到未预期的新信息温度太低会让它“不敢转弯”一旦最初的方案走不通它就反复重试同一条路。反而是 0.2 到 0.4 这个区间保留了少量探索空间让它有机会尝试备选路径又不至于过度发散。还有一个细节优先让 Agent 做“小步提交”。每次只改一个文件、只跑一个测试、只完成一个子任务然后给你反馈。这和采样参数是两套独立但互补的稳定性机制。即使采样再稳定如果任务粒度太大模型依然会在多文件、多过程的复杂度里迷路。个人体验收尾这篇写了这么多我最想说的一句话是大模型打分与采样不是研究论文里的抽象概念而是每一天都在影响你工程产出的具体机制。你只有理解了 softmax 会把分数压成概率、理解了温度改变的是分布形态才能明白为什么同一个 Agent 有时聪明有时蠢也才知道该调的是温度还是提示词而不是天天怀疑模型版本出了问题。至于 Pi Agent 这类编码智能体它们目前最适合的工作方式还是“把复杂任务拆成明确的小步骤每一步都做验证让小步反馈驱动收敛”。拿它当全自动程序员你会被它的意外操作气死拿它当高效结对编程搭档提前配置好采样参数和权限规则它能帮你节省大把时间。最后再提醒一句新版本的 Agent 配置变化很快别死记我这篇里的命令重点是把原理吃透配置跟着官方文档走就行。
大模型打分与采样原理：理解AI智能体的随机性与稳定性
经常有朋友问我一个特别拧巴的问题同一个大模型、同一段提示词为什么多跑两次结果就不一样还有人问我想让大模型自动写代码、改文件、跑测试是不是接个 API 就行这两个问题的答案其实都藏在大模型打分与采样原理里。大模型内部要先给每个候选内容“打分”再从分数分布里“采样”出最终结果而像 Pi Agent 这类智能体本质上就是把这些底层的打分离散化、把采样策略应用到一个可循环执行的任务流里。搞懂这两件事你就能解释很多“玄学”现象也能知道怎么配置一个稳定的 AI 编程助手。这篇我按自己实际使用的经验来写不堆公式吓人尽量用“这个词怎么影响你看到的结果”来讲。适合三类人想理解大模型 API 参数的人、做智能体应用开发的工程师以及正在对比 Pi Agent、OpenCode、Codex 到底哪个好用的工具党。1. 大模型“打分”到底意味着什么1.1 词元打分每一步都在做选择题很多人以为大模型是在“造句”其实不是。它更像一个超级接龙选手每次只预测下一个词元token是什么。为了预测这个“下一个词元”模型会给词表里的几万个候选词元分别算出一个分数这个分数在技术上叫 logits。logits 本身是未归一化的原始分数可以是正的也可以是负的数值大小代表模型对这个候选的“倾向程度”。光有原始分数还不行要变成能用的概率得经过一层 softmax把这批分数映射成 0 到 1 之间、且加起来等于 1 的概率分布。最后模型再从分布里挑一个词元作为输出。这整个过程就是大模型打分的核心。你可能听过“奖励模型”“打分模型”这种说法那是另外一层意思但底层本质也是类似的模型要学习如何给候选输出分配分数只不过一个用在解码环节一个用于训练和对齐。日常调试模型表现时如果你发现某些回答特别“犟”、怎么改提示词都不变那多半是某几个候选词元的分数差距太大softmax 之后几乎把概率全压在了同一个词上采样空间被压没了。1.2 用大模型当裁判另一种“打分”除了内部给词元打分现在流行把大模型本身当“评分员”用。做法很简单让模型对一段文本、一段代码或一个回答按标准打分再给点理由。这就是业内常说的 LLM-as-a-judge。这个用法在 Agent 场景里尤其重要。比如 Pi Agent 写完一段代码后可以用另一个模型或同一模型扮演审查者输出“这段代码是否通过检查分数 0-10问题点有哪些”。这比人肉 review 快得多但坑也很明显同一个模型既当运动员又当裁判容易对自己的输出有偏爱换个裁判模型分数可能就差很多。我在实战里的做法是让打分的输出固定为 JSON 结构至少要包含“score”和“reason”两个字段否则后续逻辑没法解析。打分 prompt 也要给参考标准否则模型容易“唯美是从”什么问题都打高分。最好是再做个一致性校验同一个问题问两次分数差太大的就默认无效。注意大模型打分是“相对排序”的好手不是“绝对度量”的尺子用它做质量筛选没问题想拿它当精确仪器用那是找错了工具。2. 采样原理为什么同一个模型会给出不同答案2.1 温度、Top-k、Top-p三个参数到底在调什么既然模型能给出概率分布接下来就是从分布里“选一个词元”。如果每次都是挑最大概率那个输出就固定了这叫贪婪解码后面细说。真正让模型有多样性的是采样sampling。你可以把采样想成抽奖概率大的词元中奖率高但概率小的偶尔也能冒出来。控制抽奖行为的有三个常用参数。温度temperature是最直观的。它影响 softmax 的“陡峭程度”温度越低高分数词元和低分数词元的差距被拉得越大模型越保守温度越高分布越平坦低概率词元也有机会被选到。温度调到 0 时分布变得极其尖锐几乎等同于每次选最大的那个词元。图表上你看到的所谓“创造性”本质就是温度把概率抹平了而已。Top-k 是只保留概率最高的 k 个词元当候选其余的全部归零。这种方式简单粗暴k 设太大时低概率垃圾也会混进来k 设太小时内容容易单调。Top-p 又叫核采样做法是先按概率从高到低排列候选再从高处开始累计直到累计概率超过 p 才把后面的词元裁掉。它比 top-k 聪明因为候选数量是动态的分布集中时候选少分布分散时候选多。实战里的常见组合是 temperature 0.7、top_p 0.9这是很多开源模型的默认值适合一般对话生成。要是做代码生成、Agent 决策这类需要稳定性的任务我一般会把温度压到 0.2-0.4再把 top_p 放到 0.8 左右。你可能会看到某个 API 只支持 temperature不支持 top_p那是因为厂家在服务端帮你固定了采样配置。2.2 贪婪解码、束搜索与核心采样的取舍开头说的“输出完全一样”的情况其实就是两次都相当于做了贪婪解码。贪婪解码每一步都选最大概率的词元速度最快结果稳定。但它有个毛病局部最优不等于全局最优。某一步选了个高概率词后面可能把整个句子带沟里去越说越复读机。代码生成里尤其明显容易生成重复的函数名、死循环结构。束搜索beam search则是保留多条候选序列每一步都维护 top-B 条路径最后选整体概率最高的那条。这在翻译类任务里是主力因为它能照顾到全局连贯性。但代价是计算量大而且束宽设太大时反而容易生成过于“顺滑”的废话。现在很多对话模型和 Agent 都不爱用束搜索因为对话本身就该有多样性束搜索反而把这种多样性抹掉了。还有一类进阶采样方法比如典型采样typical sampling、对比搜索contrastive search。典型采样根据“信息量是否典型”来过滤词元可以缓解模型胡编乱造对比搜索在生成时同时考虑与上文的相似度和惩罚重复刷出更连贯的文本。普通用户不需要抠这些细节但如果你在搭流式输出、做推理加速值得去了解一下效果差异还挺明显。2.3 接受—拒绝采样理论优雅落地要谨慎搜索词里频繁出现“接受拒绝采样”这在数理统计里也叫 accept-reject sampling是一种生成目标分布的通用方法。核心思路是如果你没法直接从复杂分布采样就找一个容易采样的建议分布先采一个样本再用一个接受概率决定留不留它。留下的样本近似服从目标分布。这和 LLM 有什么关系关系在于生成式模型经常想从某些复杂约束下的概率分布里采样但没法直接算。比如你希望输出“既符合语法又包含指定知识点”可以把这些要求写成打分函数先生成一批候选再用打分函数过滤。符合要求的留下不符合的丢掉这就是拒绝采样的思想。现在很多带验证器的推理方法用的就是这条路线让模型多生成几次再用打分器筛选而不是赌一次运气。实际落地时注意三点一是生成批次要够大不然过滤完没得剩二是过滤器质量要靠谱如果过滤器本身也有误差最后的结果一样漂三是延迟和成本要可控我见过最夸张的一次为了筛一篇小短文生成了二十多次候选最后效果也就比直接生成好一点点性价比很低。把它当作兜底方案用别当作默认方案。3. Pi Agent 核心原理拆解它是怎么自己干活的3.1 Agent 循环感知、规划、行动、观察Pi Agent 本质是个编码智能体不是单纯的聊天应用。普通聊天是“你问一句模型答一句”Agent 则多了一个工具调用的闭环。Pi Agent 的主体循环可以简化成四步读取当前任务和上下文让大模型规划下一步动作执行这个动作可能是执行终端命令、读写文件、搜索代码库再把执行结果返回给模型继续判断。这个循环有一个很重要的设计点模型在每次迭代时输出的不再是普通文本而是结构化的动作指令。我接触过的版本里Pi Agent 会让模型在预设的动作集合里选一种比如“查看文件内容”“执行某个测试命令”“修改某个文件的某一段”然后由外部代码去执行执行结果作为新的观察喂回模型。这样做的好处是大模型的幻觉不会直接落到文件系统里所有写操作都经过了一层“审批和校验”。为什么说它依赖打分与采样因为每次“选什么动作”本质上就是从模型对多个候选动作的概率分布里采样。如果你把温度调太高同一个任务它会一会儿想改这个文件、一会儿想跑别的命令路径非常发散调太低它可能反复尝试同一种无效方案陷在死局里出不来。所以 Agent 场景下的采样参数其实是在“探索”和“稳定”之间找平衡点。我的经验是设计代码任务的 Agent让它在主流程上偏向低温度但可以在生成具体代码内容时稍微提高一点温度这样既稳定又不至于写得太死板。3.2 技能系统把经验变成可复用的指令包Pi Agent 有“技能”Skill的概念。这和我之前用过的 Claude Code 技能类似把某个领域的专业流程、常用命令、注意事项打包成一个结构化指令模型在遇到对应任务时主动调用。举个例子我自己会给 Pi Agent 配一个“Python 测试技能”。技能内容大致是先看项目根目录有没有 pytest.ini 或 pyproject.toml确定测试框架优先运行指定测试用例失败时先看报错堆栈再决定是修代码还是补依赖。这么做的目的是把“老师傅的经验”直接塞给模型免得它每次从零摸索。技能系统的核心难点不是写文档而是拆任务。大模型擅长处理小步骤不擅长一口吞下几百行需求。所以我在技能里会写明“子任务划分粒度”比如“不要一次性修改超过三个文件”“每次改完就运行对应测试再继续”。这些约束编码成技能后Pi Agent 的稳定性会明显上升。和纯依赖系统提示词相比技能的优势在于可复用和可编排。同一个技能可以跨项目使用也可以被不同项目复用。我建议把那些你反复在项目里做的事情沉淀成技能比如“项目初始化”“数据库迁移”“lint 修复”。这些都是相对标准化的流程模型只要按技能一步步走出错的概率就会低很多。3.3 上下文管理Agent 的记忆其实是稀缺资源Agent 跑起来最常见的崩溃原因不是模型变笨而是上下文被塞爆了。Pi Agent 的工作模式决定了它会把大量工具执行结果塞回模型上下文里。如果操作的文件很大或测试输出特别长上下文很快就到窗口上限。真正的核心原理是“分层记忆”。Pi Agent 不会把所有历史一字不差地交给模型而是会做一些裁剪把早期探索过程压缩成摘要只保留当前任务相关的文件路径和结论。这有点像我记笔记重点记结论过程能一笔带过就一笔带过。你在配置 Agent 时也能看到它对“上下文预算”的控制参数比如单次工具输出的最大长度、历史消息保留量。对这部分的建议不要吝啬给 Agent 规划子任务宁可多拆几步也不要让某一步的输出过长。尤其在跑大型项目时先用搜索类工具定位相关文件再精确读取局部内容比直接把整个文件丢进去要省太多 token。4. 让 Pi Agent 跑起来安装、配置与一个完整实战4.1 环境准备与安装先用一段话讲清楚大环境Pi Agent 对运行环境的要求并不苛刻主流开发机都能跑。基本前提是有个较新的 Node.js 运行时、装了 Git、能访问你要用的模型服务。安装方式根据发布形式不同常见的是走 npm 全局安装装完会有一个命令行工具入口。我这边安装完第一件事是看版本号顺便跑一下帮助命令确认工具能正常唤起。作者在这里提醒一句这类 Agent 工具迭代很快安装命令和配置文件格式经常变最稳妥的方式是打开官方文档按当前版本的说明来。网上教程很容易过期包括我这篇里的命令也只代表我写稿时用的版本。4.2 配置模型提供商与关键参数Pi Agent 本身不内置模型它需要对接一个大模型后端。最常见的两种方式一种是配置大型模型厂商的 API Key用 OpenAI 兼容的接口地址另一种是接本地模型比如通过 Ollama 启动一个本地模型再把接口地址指到 localhost。本地模型的好处是隐私好、不花钱但长上下文处理能力和代码理解能力普遍不如商用模型跑复杂 Agent 任务容易“带不动”。配置时重点看三个东西模型名和接口地址必须填对否则所有任务都会报连接错误。主模型/快速模型拆分很多 Agent 允许设置一个能力强的“主模型”负责复杂推理再配一个便宜的“快速模型”负责简单任务比如生成提交信息、做文本摘要。合理拆分能省不少成本。采样参数前面讲的 temperature、top_p 在这里就能直接配置。生产环境任务我一般设到 temperature 0.2-0.3探索型任务可以调到 0.6。还有一个很容易被忽略但非常关键的配置权限管控。Agent 要执行命令但并不是所有命令都应该被允许。你可以配置允许执行的命令白名单、禁止执行的命令黑名单或者让关键操作先征求你的确认。我之前吃过亏没配权限就让它跑测试结果 Agent 顺手执行了一个会修改全局依赖的命令折腾了半天才恢复。权限这种东西配得越细越省心。4.3 实战演示让 Pi Agent 完成一次真实的编码任务我挑一个最常见的实战场景给你完整走一遍。任务背景一个 Node.js 项目里有一个函数用来做金额格式化结果在小数位处理上有 bug需要修复并跑通测试。我给 Pi Agent 的原始指令大概是“定位金额格式化相关函数修复精度问题补充异常用例运行测试直到全部通过”。第一步Agent 会先列出项目目录搜索关键词“format”“amount”“money”之类定位候选文件。这个过程就是模型在“打分”它要根据文件路径、函数名为哪些文件最可能是目标打分再选分数最高的那个去读。第二步读取候选文件后它会找到那个格式化函数分析精度问题的来源。如果它暂时看不出问题还会去读相关的测试文件通过测试用例反推预期行为。这里能明显看到采样参数的影响如果温度太高它可能同时产生好几个修改思路但谁也不深入温度太低它可能死死咬住最初的猜测不放。第三步Agent 会直接改文件然后运行测试。如果测试没过它会把失败信息作为新观察喂回模型再次进入规划循环。我看过它的日志前两次修的方向都是补 round 操作后来测试失败提示小数边界有问题它才改成用整数运算来避免浮点误差。整个过程走了大概六轮耗时两分钟出头。第四步测试全绿之后Agent 会整理改动文件列表和测试结果给我并建议下一步动作。到这里任务闭环就完成了。这个例子看着不复杂但内部其实经历了“候选筛选 行动序列采样 测试反馈再决策”的完整 Agent 循环。你配置的模型能力越强采样参数越贴合场景这个循环收敛得就越快。5. 实践中的坑与排查清单5.1 高频故障与排查路线我用 Pi Agent 跑了几个真实项目后整理了一份高频故障速查表你在自己实践里大概率也会撞上。卡在循环里反复执行同一条命令 大概率是前一步执行的输出没有产生有效新信息模型只能重复试探。先检查是不是命令本身超时或静默失败再考虑把任务拆得更细。另一个原因是温度太低模型死守同一个路径。适当提高温度或者手动打断在反馈里纠正方向。改的文件不对或改完引入新问题 这是典型的“定位不准”而不是“生成不准”。让 Agent 在动手前先输出“影响分析和修改计划”你确认之后再执行。很多 Agent 都支持这个确认流程不要嫌麻烦。上下文爆掉导致行为异常 观察是否在长输出、大文件后开始出现不相关的动作。缓解手段包括让工具只输出文件的关键片段、限制测试输出的行数、定期用摘要替代历史消息。如果 Agent 支持记忆压缩配置调高压缩阈值。模型返回格式偶尔不合法 工具调用依赖结构化输出偶尔模型会给出残缺的 JSON 或者字段名不对导致解析失败。这类错误通常是外部的可以设置自动重试或者临时换成能力更强的模型来处理工具调用。5.2 采样参数与 Agent 稳定性的实战建议先把结论放在前面如果你希望 Pi Agent 干活足够“稳”temperature 和 top_p 的推荐区间是 0.2-0.4 和 0.7-0.9。这和一个聊天助手动辄用 0.8-1.0 的配置很不一样原因在于 Agent 的任务是执行多步操作中途每多一次采样波动就会多一分路径偏差。写文案可以放飞但改代码和跑命令必须收敛。我也试过把温度调到 0结果同样不理想。问题在于Agent 的每一步都可能遇到未预期的新信息温度太低会让它“不敢转弯”一旦最初的方案走不通它就反复重试同一条路。反而是 0.2 到 0.4 这个区间保留了少量探索空间让它有机会尝试备选路径又不至于过度发散。还有一个细节优先让 Agent 做“小步提交”。每次只改一个文件、只跑一个测试、只完成一个子任务然后给你反馈。这和采样参数是两套独立但互补的稳定性机制。即使采样再稳定如果任务粒度太大模型依然会在多文件、多过程的复杂度里迷路。个人体验收尾这篇写了这么多我最想说的一句话是大模型打分与采样不是研究论文里的抽象概念而是每一天都在影响你工程产出的具体机制。你只有理解了 softmax 会把分数压成概率、理解了温度改变的是分布形态才能明白为什么同一个 Agent 有时聪明有时蠢也才知道该调的是温度还是提示词而不是天天怀疑模型版本出了问题。至于 Pi Agent 这类编码智能体它们目前最适合的工作方式还是“把复杂任务拆成明确的小步骤每一步都做验证让小步反馈驱动收敛”。拿它当全自动程序员你会被它的意外操作气死拿它当高效结对编程搭档提前配置好采样参数和权限规则它能帮你节省大把时间。最后再提醒一句新版本的 Agent 配置变化很快别死记我这篇里的命令重点是把原理吃透配置跟着官方文档走就行。
