Skip to content

数据模型

所有数据模型均在 src/models.py 中定义为 Pydantic BaseModel 子类，并进行严格验证。模板定义位于 src/templates.py。

核心模型

这些模型代表流经管道的主要数据结构。

ExtractionResult

提取阶段的输出。包含在一页或多页 PDF 上检测到的所有表格和上下文条目。

字段 类型 描述
tables list[TableModel] 所有检测到的表格（主表、辅助表、其他）
context list[TextContextModel \| ImageContextModel] 所有非表格上下文条目

TableModel

从文档页面提取的单张表格。

字段 类型 描述
table_id str 生成的标识符（如 table_0_0）
role TableRole MAIN、AUXILIARY 或 OTHER
page_number int 来源页码
headers list[str] 按顺序排列的列表头
rows list[dict[str, str]] 以表头名称为键的行数据
confidence float 提取置信度（0.0–1.0）
notes str \| None 提取异常说明
bbox BoundingBox \| None 页面上的归一化边界框
primary_key_column str \| None 唯一标识行的列标题

TextContextModel

基于文本的上下文条目（通用备注、规范要求、技术规格）。

字段 类型 描述
context_id str 生成的标识符
type ContextType 始终为 TEXT
page_number int 来源页码
content str 完整的逐字文本内容
category ContextCategory 文本块的分类
category_detail str \| None 附加分类信息
scope list[str] \| None 该上下文适用的行 ID

ImageContextModel

基于图像的上下文条目（图例图示、条目卡片、尺寸图）。

字段 类型 描述
context_id str 生成的标识符
type ContextType 始终为 IMAGE
page_number int 来源页码
content str 文件路径或占位符标识符
format str 图像格式（如 png）
dimensions tuple[int, int] 图像尺寸
interpretation str \| None 对图像内容的详细文字描述

EnrichedRow

富化阶段的最终输出。每条主清单行对应一个实例。

字段 类型 描述
row_id str 主清单中的主键值
data dict[str, str] 以模式列名为键的列值
field_sources dict[str, FieldSource] 每个已填充字段的来源
confidence float 所有参与专业策略中的最低置信度
reasoning str \| None 所有专业策略推理的拼接结果

UserTableSchema

用户定义的输出模板，控制管道填充哪些列。

字段 类型 描述
template TemplateType 模板类型（如 STANDARD_TAKEOFF）
columns list[str] 按顺序排列的目标列名

模型验证器确保 Special Notes 始终是最后一列，无论用户在列表中将其置于何处。

核心模型关系

下图展示核心模型之间的关系。

classDiagram
    class ExtractionResult {
        tables: list~TableModel~
        context: list~ContextModel~
    }

    class TableModel {
        table_id: str
        role: TableRole
        headers: list~str~
        rows: list~dict~
        primary_key_column: str
    }

    class TextContextModel {
        context_id: str
        type: ContextType
        content: str
        category: ContextCategory
    }

    class ImageContextModel {
        context_id: str
        type: ContextType
        content: str
        interpretation: str
    }

    class EnrichedRow {
        row_id: str
        data: dict~str, str~
        field_sources: dict~str, FieldSource~
        confidence: float
    }

    class UserTableSchema {
        template: TemplateType
        columns: list~str~
    }

    ExtractionResult "1" *-- "many" TableModel
    ExtractionResult "1" *-- "many" TextContextModel
    ExtractionResult "1" *-- "many" ImageContextModel
    ExtractionResult --> EnrichedRow : 富化为
    UserTableSchema --> EnrichedRow : 定义列

枚举类型

管道枚举

枚举 值 用途
TableRole MAIN、AUXILIARY、OTHER 分类表格在文件中的功能
ContextType TEXT、IMAGE 区分文本和图像上下文条目
ContextCategory GENERAL_NOTE、PERFORMANCE_SPEC、MATERIAL_REQUIREMENT、STRUCTURAL_CRITERIA、CODE_REQUIREMENT、OTHER 分类文本上下文内容
FieldSource MAIN_TABLE、AUXILIARY_TABLE、TEXT_CONTEXT、IMAGE_CONTEXT、UNRESOLVED 追踪填充每个字段的来源
StrategyType AUXILIARY_TABLE、TEXT_RULE、IMAGE_LEGEND、DIMENSION_CARD、MULTI_LABEL 标识专业富化策略
MatchType EXACT、FUZZY、RULE_BASED、UNMATCHED 匹配质量分类（用于旧版解析）
ModelType FAST、ADVANCED 选择 Gemini 模型层级
TemplateType STANDARD_TAKEOFF、STANDARD_TAKEOFF_TDL、GLASS_SCHEDULE、SHOP_DETAILS 预定义输出模板

领域枚举

枚举 示例值 用途
WindowOperabilityType Casement Single、Direct Set / Picture / Fixed、Awning、Sliding Window、Double Hung 窗户的约束开启方式值
DoorOperabilityType Swing Single、Swing Double、Sliding Door、Folding、Pivot 门的约束开启方式值

填充 Operability 列的专业策略必须使用这些枚举中的值。约束字符串在运行时通过 _build_operability_constraint() 注入提示词。

Gemini 响应模型

这些模型定义了 Gemini 返回的结构化 JSON 模式。每个模型对应一个特定的管道步骤。

模型 使用方 返回内容
GeminiTableResult TABLE_EXTRACTION 提示词 list[GeminiTableModel] — 检测到的表格
GeminiContextResult CONTEXT_EXTRACTION 提示词 list[GeminiTextContextModel \| GeminiImageContextModel] — 上下文条目
GeminiRoutingResult ROUTER 提示词 list[StrategyType] + 推理依据
GeminiEnrichedRowResult 所有富化提示词 list[GeminiEnrichedRow] — 含字段来源的富化行
GeminiResolutionResult FUZZY_MATCHING、SEMANTIC_MATCHING list[GeminiResolutionModel] — 匹配结果（旧版）
GeminiCompoundResolutionResult COMPOUND_RESOLUTION list[GeminiCompoundResolution] — 主/次组件拆分
GeminiRuleApplicationResult RULE_APPLICATION list[GeminiRuleApplication] — 规则映射至行
GeminiColumnDetectionResult COLUMN_DETECTION list[GeminiColumnMatch] — 表间列关联

所有 Gemini 响应模型均继承自 GeminiResponse，提供 confidence（浮点数，0.0–1.0）和 notes（异常情况的可选字符串）。