4.1 环境搭建与数据准备
4.1 环境搭建与数据准备
本节摘要：动手编译前的全部准备工作：安装与 LM 配置、检索底座的两种接法、训练数据的标注规格与切分策略。数据是编译的原料——本节后半部分给出的"五十条起步"判断与质量抽检流程，直接决定后面每一次编译的下限。
一家做企业内部知识库的团队曾经问过我们：编译前到底要准备多久？答案是环境半天、数据看情况——环境从来不是瓶颈，数据的规格与质量才是。本节按这个经验组织：先把环境一次配齐，再把主要篇幅留给数据。
环境搭建的最短路径
安装只需一行包管理命令，之后的核心动作是把语言模型配置成 DSPy 的全局默认。现代版本的配置集中在 dspy.LM：
import dspy # 用任意兼容 OpenAI 接口的模型；本地部署的开源模型同样只需换 base_url lm = dspy.LM( "openai/gpt-4o-mini", # 模型标识：供应商前缀加模型名 api_key="你的密钥", temperature=0.7, # 编译期建议保留随机性，利于搜索多样性 max_tokens=512, ) dspy.configure(lm=lm) # 先做一次冒烟测试再往下走 print(dspy.Predict("question -> answer")(question="法国的首都？").answer)
三个参数值得说明。模型标识里的供应商前缀决定了协议适配方式，换供应商只换这一串字符串——这正是第 2 章"可移植性"的落点。temperature 在编译期与运行期可以不同：编译期留一点随机性让自举轨迹更多样，运行期（尤其是结构化抽取任务）通常压到接近零以求稳定。max_tokens 要按任务给足，思考型模块会先输出推理段，给少了会截断在半截推理上，解析报错还找不到原因。
需要检索时，再接一个检索底座。两种典型接法：
# 接法一：外部检索服务（以 ColBERT 类服务为例） rm = dspy.ColBERTv1(url="http://你的检索服务地址", index_name="kb_docs") dspy.settings.configure(rm=rm) # 接法二：零依赖起步，用内置的本地文档检索（适合原型与教程） # dspy.Retrieve 在配置了任一检索底座后即可在 Module 里直接使用
没有检索服务时，原型阶段可以用内置检索兜底，把检索质量优化留到工程化阶段——检索质量与提示词质量是两个正交问题，初学阶段混在一起排查只会更乱。
数据标注的最小规格
编译用的每条样本就是一个 dspy.Example，最小规格只有两个字段：输入与最终答案。以问答任务为例：
trainset = [ dspy.Example( question="公司差旅报销的审批时限是几天？", answer="三个工作日内", ).with_inputs("question"), # 声明哪些字段是模型输入 # with_inputs 的意义：编译器据此区分"喂给程序的"与"只用于打分的" ]
规格虽小，纪律不少。第一，答案要写"验收标准"而不是"参考答案"——如果标准答案是"三个工作日内"，编译器自举时会把一切其他表述判错，因此答案的粒度必须与指标匹配（用 exact_match 就写唯一标准写法，用语义裁判则可以放宽）。第二，输入要覆盖真实分布：从线上日志里抽样，比工程师手造的问题更有编译价值，手造问题往往太干净，编译出的示范撑不住真实用户的歪歪扭扭。第三，脏数据宁缺毋滥：标注环节最好安排两人交叉抽检，错误率控制在一个较低的百分比以内——示范是模型模仿的对象，示范带毒等于定向教错。
切分策略与量级判断
数据要切成三份，职责各不相同：训练集喂给编译器（自举示范的原料），验证集给编译器内部挑选候选（搜索的评分场），测试集只做最终验收（你与团队汇报用的数字）。典型比例按数据量浮动：百条级别可以四比三比三；数据充裕时八比一比一也行。铁律只有一条：测试集绝不参与任何编译与调参决策，否则它就退化成了第二验证集，最终数字全部失真。
量级判断的经验值：单预测器程序，五十条训练集就能支撑一次像样的自举编译；每增加一个参与编译的预测器，示范需求近似翻倍——三层深度、每层一个预测器的程序，几百条训练集才算及格。验证集按候选数量放大：BootstrapFewShotWithRandomSearch 要为约八个候选打分，百条以内的验证集勉强可用；MIPROv2 的试验数（num_trials）乘上验证集规模就是它的评估开销，据此倒推验证集规模更稳妥。数据实在凑不够时的正规做法不是硬编，而是缩小程序（合并预测器）或降低搜索档位，让结构复杂度与数据规模重新配平——4.3 节会再次回到这条配平原则。
准备工作的验收清单
环境侧四项：模型冒烟测试通过；temperature 与 max_tokens 按编译期口径设置；检索底座连通并抽查三条查询的返回质量；密钥与配额确认能扛住编译期的调用洪峰（自举会对训练集反复调用，量级估算见 4.4）。数据侧四项：训练验证测试三份切分完成且测试集封存；每条样本都过了 with_inputs 声明；交叉抽检的错误率达标；输入分布与线上真实分布对过表。八项全绿，再进 4.2 的第一次编译——否则后面每一次编译失败，你都得先怀疑地基。
补一个关于成本的现实提醒：环境准备的最后一项是配额测算。用一份十页的典型文档、一条典型问句，手工模拟一次完整的编译期调用链（检索几次、生成几次、各多少 token），把单样本成本乘以训练集规模与自举轮数，就得到一次编译的预估开销。很多"编译翻车"的事故复盘到最后，发现根因只是配额中途耗尽、调用被静默限流，轨迹残缺导致自举质量崩塌——十分钟的成本测算，省掉的是数小时的排错。
本节要点回顾
- 环境半天：
dspy.LM三参数（模型标识、temperature、max_tokens）决定编译期行为；换供应商只换标识字符串。 - 检索分两步走：原型用内置检索兜底，检索质量优化留到工程化阶段，与提示词问题隔离排查。
- 答案即验收标准：标注粒度必须与指标匹配；输入从线上分布抽样；交叉抽检控错率。
- 三分切分：训练集自举、验证集选候选、测试集封存只做验收；数据量按预测器数量配平。
- 通向下一节：地基打牢，下一节跑通第一个编译产物，看编译前后的真实差异。