0.2 路线图与环境准备

0.2 路线图与环境准备

本节摘要：本节帮你选定路线并备好环境。三条路线对应三类读者：快速上车型（第 2+3+4 章，约半天，产出一台本地决策服务）、微调定制型（第 3+5+7 章，约两三天，产出带置信门控的定制决策器）、架构选型型（第 0+6+9+10 章，约一小时，产出一份有理由的选型结论）。环境准备只有三步：Python 3.10 以上、pip 安装 laya、首次调用自动下载检查点；无需 GPU，BERT 级参数量 CPU 可跑（官方 README 口径）。本节以自检脚本收尾，并用一张分工图交代本书与《Jev 决策编程》《Kev 实战》的边界：概念归前者，重型训练归后者，本书专注「用现成检查点的轻量自托管路线」。

学习目标

• 从三条学习路线中选出适合自己的那条，并说出它的产出与耗时。
• 完成环境三步准备并通过自检脚本。
• 知道模型下载发生在首次调用、离线环境如何提前准备。
• 说清三本书的分工：概念、轻量路线、重型路线各归哪本。

一、三条学习路线

三条路线对应三类读者，先对号入座再往下读：

三条路线都从环境准备开始，也都默认你读过第 0.1 节——「该不该用 laya」比「怎么用 laya」优先级更高。

快速上车型不看微调：先用官方检查点把链路打通，验证延迟与接口形态满足预期，微调是打通之后的事。微调定制型是本书的主干读法：第 5 章会用官方提供的 Kaggle 2×T4 免费 GPU notebook（官方口径），不买卡也能完成训练；第 7 章的校准与弃权是微调后的收口动作，跳过它等于把没校准的概率直接暴露给线上。架构选型型可以完全不动手：第 6 章讲清长文本与高基数的边界，第 9 章给三向对照，第 10 章给陷阱清单，读完就能写选型结论。

二、环境准备：三步

第一步，确认 Python 版本。laya 要求 Python 3.10 以上（官方口径），建议在虚拟环境里安装，保持依赖干净。

# bash —— 环境准备（安装命令以官方仓库 README 为准）
python --version                 # 确认 3.10 以上
python -m venv .venv && source .venv/bin/activate   # Windows 用 .venv\Scripts\activate
python -m pip install laya        # 基础 SDK：predict / predict_batch / decide
​

第二步，按需装可选组件。HTTP 服务、MCP server、LangChain 集成都是可选依赖，用到哪章再装哪章。

# bash —— 可选组件（按需安装，写法示意）
python -m pip install "laya[serve]"       # 第 4 章：laya-serve HTTP 服务
python -m pip install "laya[mcp]"         # 第 8 章：MCP server
python -m pip install "laya[langchain]"   # 第 8 章：LangChain 集成
​

第三步，验证导入成功。不需要提前下载模型——laya 的检查点在第一次调用时自动下载（官方口径），本章自检只验证包可用。

三件不需要做的事：不需要 GPU（BERT 级参数量 CPU 可跑，官方 README 口径）；不需要申请 API Key（自托管，无云端鉴权环节）；不需要预先懂 BERT 原理（底座细节只讲到选型够用，见《教程规划》的内容边界）。

两件容易被忽略的小事。磁盘：检查点加起来有可观的磁盘占用，给项目目录与缓存目录都留出余量（缓存路径以官方文档为准）。网络：首次下载依赖外网，服务器在内网的话，先在有网的机器上触发下载、再迁移缓存目录，或走第 4.2 节的容器预下载路线。

三、动手前的自检

# check_env.py —— 动手前三步自检
import sys

print("python:", sys.version.split()[0])
assert sys.version_info >= (3, 10), "需要 Python 3.10 以上"

try:
    import laya
    print("laya 已安装:", getattr(laya, "__version__", "未知版本"))
except ImportError:
    print("laya 未安装，请执行: python -m pip install laya")

print("GPU 非必需：BERT 级检查点 CPU 可跑（官方 README 口径）")
print("检查点将在首次调用时自动下载，请保证网络与磁盘空间")
​

三个提醒。其一，首次调用会下载检查点，几个检查点加起来有可观的磁盘占用，容器或离线环境请提前下载并挂载缓存目录（第 4.2 节给出容器内预下载的写法）。其二，中国大陆网络环境下模型下载可能较慢，可考虑先行下载后放置到缓存目录，具体路径以官方文档为准。其三，练习代码建议统一放在一个目录里，全书代码块首行都标注了文件名，按名建文件即可复现。

四、三本书的分工

这套决策编程方向的书有三本，分工如下：

                《Jev 决策编程》
          概念层：为什么判断型决策值得单独一种模型
          三原语与心智模型（第 02、03 章），实战书都不重讲
                        │
          ┌─────────────┴─────────────┐
          ▼                           ▼
   《Laya 实战》（本书）          《Kev 实战：训练并运行
   轻量自托管路线                 你自己的决策模型》
   用现成检查点：三检查点与        重型训练路线
   Router、SDK、laya-serve、      自训检查点：数据、训练、
   Docker、ONNX、轻量微调          运维；协议全景在第 01 章
​

分工的实际含义：读本书第 1 章遇到「System 1」「typed 三原语」概念不熟，回《Jev 决策编程》第 02、03 章；读本书第 4 章想深挖 /v1/systemone 协议字段，去《Kev 实战》第 01 章《协议与兼容》；想在 laya 之外自训一个完全属于自己的决策模型，整本《Kev 实战》都是那条路。本书不重复这三块内容，篇幅全部留给「把 laya 用对」。

五、版本与变动预期

laya 是活跃开发期的开源项目，三点预期要提前建立：CLI 参数与 API 字段可能随版本变动，本书标「写法示意」处以官方仓库 README 为准；检查点清单与默认路由策略可能演进，以官方文档为最终口径；官方 README 的数字（延迟、参数量、微调收益）是发布时点的口径，复测时以自己环境为准。建立这三点预期后，官方文档与本书不一致时你不会慌——以官方为准，本书负责讲清结构与思路。

六、常见安装问题速查

七、全书产出物清单

按路线读完之后，你手上应该有这些东西：

这份清单也是自查进度的尺子：哪一行的产出物还没有，对应章节就还没真正读完。

最后说一句节奏。三条路线都不必一口气读完：快速上车型跑通服务后就停下来接一个真实小场景，微调定制型在第 5 章前先把第 3 章的脚本改造成自己的问题表——每一段读完都有东西落地，比连续读完十章的留存率高得多（经验之谈，非实证结论）。

本节要点回顾

• 三条路线：快速上车型（2+3+4，半天，产出服务）、微调定制型（3+5+7，两三天，产出定制决策器）、架构选型型（0+6+9+10，一小时，产出选型结论）。
• 环境三步：Python 3.10 以上、pip 安装 laya、首次调用自动下载检查点；无需 GPU、无需 API Key。
• 三本书分工：概念归《Jev 决策编程》，轻量路线归本书，重型训练归《Kev 实战》。
• 变动预期：写法示意以官方 README 为准，数字是发布时点口径。

环境就绪、路线选定，可以进入正文了。下一章先把两个心智模型立稳——System 1 决策与自回归生成的工程分界，以及 typed 三原语在 laya 里的具体形态——之后再动手写代码，每一步都知道自己在操作什么。