4.1 环境搭建与安装

4.1 环境搭建与安装

本节摘要：安装不只是一条安装命令。Parlant 是规则优先的执行引擎，环境必须能复现开发时定义的行为。对照笔记本全局包、通用 Agent 随便起一个密钥、规则引擎重型中间件，这里要轻量运行时加严格依赖一致性：Python 3.10+、虚拟环境、异步栈、可选 Web 服务组件，模型后端不强制绑定。

阅读收获

阅读完本节，你应当能够：

1. 解释「计算契约」：环境不一致等于行为不可复现
2. 对照同步 HTTP 库为何会破坏事件循环
3. 列出原文提到的配置维度：日志、监听、密钥、会话存储
4. 说明容器化解决的是环境漂移，不是架构本身

轻量运行时，不等于随便装

原文：核心 Python 实现，不必 GPU，可跑在边缘或低成本实例。但对 Python 版本、异步库、第三方依赖敏感——规则引擎对状态机和上下文很挑。因此搭建是确认契约：这台机器能否精确复现行为。

官方推荐安装命令是 pip install parlant。原文截至 2024 年中描述的关键依赖方向包括：数据校验与序列化库以支撑工具输入输出类型、异步 HTTP 客户端、可选的 Web 服务与 ASGI 服务器、环境变量加载。具体版本下限以当时发行说明为准，教程不把某一补丁号写成永远正确。

未强制绑定某一家大模型。模型调用被抽象成工具的一种。灵活，也要求你自己把所选客户端与认证配好——这和「安装框架就送一个默认脑」的通用 Agent 不同。

必须用虚拟环境隔离。团队应锁定依赖清单，保证可复现。Windows 与类 Unix 的激活方式不同，原则相同：别污染系统解释器。

开发机契约（概念）：
[虚拟环境] → [框架及声明依赖] → [你选择的模型客户端]
         → [异步事件循环]
         → [会话/客户存储后端]
不要：系统全局包 + 同步阻塞客户端 + 内存存储直接当生产
​

异步是执行上下文，不是语法糖

工具须声明为异步，主程序在事件循环中。天气查询概念：装饰器注册、p.Server 上下文里 create_agent、再挂工具。若在工具里打同步请求，循环阻塞，延迟和死锁都会来。对照规则引擎常见同步服务：那边线程模型不同，抄同步习惯会在这里翻车。

ToolContext 提供会话、用户、历史。分布式部署时这些要靠状态后端，不是工具函数私自记在内存。环境配置的另一维是存储：原型内存，本地 JSON，生产 MongoDB——第 1 章已对照，这里是落地选择。

原文提到的配置项方向：日志级别、内置服务监听地址与端口、若用托管服务则需认证密钥。开发可用环境变量文件加载；生产应用平台密钥设施，避免把秘密写进镜像说明文字。本教程不给具体文件名路径。

⚠️ 常见坑：在能跑通的笔记本上直接对生产数据库做工具查询。环境契约包含权限边界：开发应用沙箱数据。
💡 关键直觉：飞控软件的地面模拟器必须和机载版本同源。环境漂移等于你在用另一套飞控做认证。

容器化与「一次构建」

原文鼓励容器化消除「我机器能跑」。示例思路：精简官方 Python 基础镜像、只装依赖、非 root 运行、把配置从构建参数拆走。官方是否提供预构建镜像以当时文档为准，不编造镜像名。编排层可用平台配置注入密钥与连接串。

从定义规则到运行：本地环境变量 → 流水线镜像 → 云上密钥。目标始终是行为确定与安全边界。监控与日志策略在这一步就要有，不要等第 5 章出事再补——环境是治理的第一道。

依赖一致性检查：升级框架前在预发把关键 Journey 跑一遍。模型客户端升级同理。环境契约包括「已知可工作的组合」，不是最新即最好。

问题 没有 GPU 能做吗？

能。原文写核心不必 GPU。GPU 只在你把本地大模型当工具后端时才可能需要，那是你的模型选择，不是框架门槛。

问题 必须上 MongoDB 吗？

不是。本地 JSON 适合轻量。生产要并发与运维能力时再换。不要在教程里把 MongoDB 写成唯一合法后端。

从安装到预发的对照清单

安装命令能成功，只说明包管理器工作。真正的环境验收是：在干净虚拟环境里拉起服务，跑通一条含工具失败的 Journey，审计里能看到拒绝或转人工。没有失败路径的安装验收，等于只验了幸福。对照「notebook 能 chat」。

依赖锁定要进版本库。升级框架或模型客户端走预发回归，回归集是关键指南路径，不是随机闲聊。原文依赖方向里的校验库、异步客户端、可选 Web 组件，按你是否启用内置服务来装，不必为了完整把可选栈全开。开得越多，攻击面越大。

密钥与连接串禁止进对话示例和镜像说明。开发用本地环境变量，生产用平台注入。会话存储选错的典型是：演示用内存，上线忘了改，重启丢会话，用户以为被耍。发布检查必须包含存储后端项。

异步纪律写进代码规范：禁止在工具里调用同步阻塞网络库。发现一次就当缺陷，不当风格问题。事件循环被堵时，所有用户一起慢，排错会误判为模型配额。环境问题常伪装成模型问题，这是本章对照的核心。

容器化解决漂移，不解决权限。镜像里若预装了生产凭证，漂移没了，泄漏有了。非特权用户运行、只读根文件系统、配置外置，这些是容器的计算契约延伸。官方是否提供现成镜像以当时文档为准，自己构建时按契约检查，不按「能跑」检查。

干净房间安装

准备一台没有全局包的机器或容器，只按契约安装，跑失败路径。能过，安装文档才算真。开发者自己的电脑往往有残留依赖，会掩盖契约破裂。对照「在我机器上能跑」。干净房间每月做一次，尤其在升级之后。另外把 Python 主版本写进文档，原文是 3.10 以上，不要默默用更旧的解释器直到异步语法报错才发现。环境章的敌人是侥幸，侥幸的样子很像效率。

对照作业：干净房间与依赖锁定

围绕「干净房间与依赖锁定」，把四条路径再过一遍。表里每格都是可执行判断，不是形容词。读完请把你的项目钉进一格，不要钉在两格之间假装都占了。

安装命令成功只说明包管理器工作。验收是失败路径轨迹可见。没有失败的安装验收，只验了幸福。

容器消除漂移，不消除凭证进镜像。非特权运行、配置外置，才是契约延伸。

钉列纪律：环境契约与干净房间

在「环境契约与干净房间」上，纯 prompt 把判断写进一段话，改的人必须会改提示，复盘只能翻聊天，口语进得来但口径会漂。通用 Agent 把判断交给循环，灵活的代价是越权与路径不可复现。规则引擎把判断写进分支，确定的代价是口语进不来、改口径要排期。Parlant 把判断写成指南与契约：业务改口径，未授权则无行动，复盘指轨迹。把这四句贴到工位上，比再记一组术语有用。

针对环境契约与干净房间，本周只做一件可验收的事：找出一条真实对话或工单，标注它今天落在哪一列；若要迁到第四列，缺的是指南、工具还是关系边。缺指南就写草稿，缺工具就列契约，缺关系就补消歧或依赖。不要同时开十条战线。最常见的伪装是文件名叫指南、真源仍是提示词，或者架构图上有网关、运行时模型仍直接调函数。用「改文本能否改行为」和「低权限点名是否被拒」两张试纸识破。识破了再谈优化与案例。优化在伪装上加速，只会让错误承诺更多；案例在伪装上复制，只会把新闻变成事故。

环境契约与干净房间的纪律是先钉列，再谈快。钉列需要抽检，抽检需要轨迹，轨迹需要审计真的在记抑制原因，而不只记最终回复。若没有抑制原因，排错会以为没写规则，其实是优先级压了。看得见「为什么没走另一条路」，才叫对照，才叫可控。把这句话写进值班手册，环境契约与干净房间才从概念变成岗位。对照驱动不是文风，是岗位制：模型是引擎和笔杆子，方向盘在指南与工具契约上。谁把方向盘又塞回提示词，谁就在环境契约与干净房间上退回第一列。

要点串联

• 安装是契约：复现行为比装上包更重要
• 3.10+ 与虚拟环境：依赖敏感，隔离
• 不绑模型厂商：你要自己接认证
• 异步强制：同步客户端会卡死循环
• 配置分层：开发变量 vs 生产密钥设施
• 容器对漂移：不替代 Journey 与权限设计

下一节写灵魂：Journey 如何把 SOP 变成可执行蓝图，而不是让模型现场编流程。