一、Pydantic Schema介绍

Python 里 Pydantic 是专门做 Schema 建模的工具，写类+字段类型，它就能自动帮你校验数据、转换类型，后端和AI项目基本都这么写。

所谓Schema，通俗解释就是规定数据长什么样——有哪些字段、什么类型、哪些必填、哪些可选。

我们即将要建的 src/schema.py，就是用Pydantic定好小说数据的格式。之后程序读写数据，都会按这个模板来校验，省得字段乱、类型错。

小编之前踩过full_summary缺失的坑、index和order字段名不匹配问题，根源就是数据模型和 AI 输出规范没对齐，Schema 就是解决这类问题的第一道防线。

二、搭建 schema.py 数据模型文件

① 新建文件目录

在项目根目录创建src文件夹，文件夹内新建schema.py空白文件。

 

② 使用 Cline 插件自动生成代码

打开 VS Code 侧边栏 Cline 插件，输入如下指令，精准指定文件路径与建模需求：

@/src\schema.py 用pydantic建模这个小说系统的数据结构。
要表达：
- 一本小说有标题、主题、全书概括，以及若干章节
- 每个章节有：先后顺序、标题、本章要写的情节要点、一些可选的线索

关键设计点：章节还要能装"正文". 流程是-规划阶段生成大纲(这时各章节为空)，写作阶段在逐步把正文填进去，最后整体交个导出。所以不要为“已经写完的章节”单独建一个类：同一个章节模型，正文字段从空到满就行

（可根据自己的要求修改指令）

 

③Cline 分步执行流程

1. 输入指令后，切换到插件右下角Plan模式，按下回车让 AI 生成开发计划；
2. 仔细核对生成的规划内容，确认完全贴合我们的建模需求，无多余冗余设计；
3. 规划无误后切换至Act执行模式，AI 会自动生成完整 Python 代码；
4. 通读生成的源码，核对字段名、校验规则、默认值全部匹配需求，确认无 bug 后点击Save写入 schema.py 文件。

 

 

补充：此处附上我本次生成完成、可直接粘贴使用，小伙伴们也可以对照 AI 生成结果查漏补缺。

from __future__ import annotations
from pydantic import BaseModel, Field

class Chapter(BaseModel):
    """小说中的一个章节。"""
    order: int = Field(..., ge=1, description="章节序号")
    title: str = Field(..., min_length=1, description="章节标题")
    outline: str = Field(..., descreption="章节大纲") 
    plot_points: list[str] = Field(
        default_factory=list,
        description="本章要写的情节要点",
    )
    clues: list[str] = Field(
        default_factory=list,
        description="可选的线索，写作阶段可逐步补充",
    )
    body: str = Field(
        default="",
        description="正文内容；规划阶段可为空，写作阶段逐步填充",
    )


class Novel(BaseModel):
    """一部小说的整体数据结构。"""
    title: str = Field(..., min_length=1, description="小说标题")
    theme: str = Field(..., min_length=1, description="小说主题")
    full_summary: str = Field(..., min_length=1, description="小说全文概括")
    chapters: list[Chapter] = Field(
        default_factory=list,
        description="小说章节列表",
    )

 

三、代码完整友好解析

3.1 头部导入语法逐句讲解

from __future__ import annotations
from pydantic import BaseModel, Field

1. from __future__ import annotations
   兼容前置引用语法，允许在Novel类里直接写list[Chapter]，不用额外做类型延迟导入，新手写结构化数据模型必加。
2. BaseModel
   Pydantic 所有数据模型的父类，自带全套能力：自动校验数据、对象一键转 JSON、JSON 一键转 Python 实例，是整套 Schema 的基石。
3. Field
   自定义字段约束工具，用来设置必填标识、数值范围、默认值、字段说明文字，精细化管控每一项数据规则。

3.2 字段配置区分规则（高频考点）

• Field(...)：代表必填字段，创建模型实例时必须传入内容，缺失直接抛出校验报错；
• default=""：字符串字段默认空文本，适配章节正文初期空白的场景；
• default_factory=list：列表类型专用默认值，千万别直接写 default=[]，会出现全局列表共享、数据错乱的经典 Python 坑，用 default_factory 每次都会生成全新空列表。

3.3 两大核心数据模型拆解

① Chapter 单章节模型（复用型设计）

字段划分：

（1）必填项：order章节序号、title章节标题、outline章节大纲

 - 附加约束：order 数值必须≥1，杜绝 0、负数章节序号；标题不能为空字符串；

（2）可选项：

 - plot_points情节要点、clues故事线索：默认空列表，规划阶段可逐步补充；

 - body章节正文：默认空字符串，完美适配项目流程 —— 生成大纲时留白，逐章扩写后填充完整正文，全程只用一套模型，不用重复写两套类。

② Novel 整本小说顶层模型

全部核心基础字段均为必填：小说标题 title、主题 theme、全书梗概 full_summary，三项缺一不可；
可选字段：chapters章节列表，默认空集合，内部存储多个 Chapter 对象。

小提示：模型内所有字段名称都可以根据自己的习惯自定义，只要配套修改提示词、JSON 清洗逻辑即可，灵活度很高。

 

文末收尾 & 下集预告

本节我们完成了项目核心数据模型的定义，搭建起小说数据的标准模板，从根源规避后续 LLM 输出 JSON 解析失败的问题。
下一节预告：【Python LLM 小说自动化生成实战】3｜项目.env 配置文件设计，统一管理 API 密钥、模型参数、重试次数等全局变量。
🔗 本系列专栏合集传送门：小白入门！从零实战开发Python LLM小说自动化生成系统