[Meetily后端框架] AI摘要結構化 | `SummaryResponse`模型 | Pydantic庫

第3章：摘要數據結構（Pydantic庫）

歡迎回來！

在之前的第2章：API文檔中，我們知道API網關提供了端點

而API文檔準確告訴我們如何與這些端點通信，包括需要發送的數據格式和期望接收的數據格式。

我們期望接收的最重要數據之一是會議摘要。

但在計算機程序中，會議摘要究竟應該是什么樣子的？

它不僅僅是一個大段的文本。我們希望它是有結構的，包含明確的行動項、決策等部分，以便應用程序可以輕松地美觀顯示或提取特定條目。

這就是摘要數據結構的意義所在，在我們的項目中，我們使用**Pydantic模型**來定義和強制實施這種結構。

定義數據結構解決了什么問題？

假設我們需要給朋友寫信。可以自由發揮——從天氣開始，聊聊日常生活，最后再補充一些內容。這非常靈活！

現在想象我們正在填寫工作申請表。這是不靈活的。它要求我們在不同的方框中填寫姓名、地址、工作經歷等具體字段。

這種明確的格式要求是因為公司需要高效處理這些信息。

在編程中，特別是當應用程序的不同部分（如后端和前端）甚至不同程序（如我們的后端與AI模型交互）需要交換復雜信息時，這些信息需要像表單一樣結構化，而不是自由格式的書信。

如果后端像這樣發送摘要數據：

{"MeetingTitle": "Project Alpha Kickoff","ActionItemsList": ["Send intro email to team by Friday","Schedule follow-up sync next week"],"DecisionsMade": [{"decision": "Use Tool X", "who": "Team Lead"},{"decision": "Timeline set to 6 weeks", "who": "Project Manager"}]// ... 其他字段 ...
}

而后端開發者后來不小心將"ActionItemsList"改為"ActionsToDo"，或者更改"DecisionsMade"的結構，期望舊格式的前端開發者會遇到應用程序崩潰的問題！

我們需要一種方法來明確定義數據的預期格式，并確保數據始終遵循這種格式。

引入Pydantic模型：數據的藍圖

本項目使用名為Pydantic的Python庫來解決這個問題。

Pydantic允許我們使用標準Python類和類型提示來定義數據的*結構*和*類型*。這些類定義就成為我們的Pydantic模型。

將Pydantic模型視為數據的藍圖或模板。它規定了：

數據應包含哪些"字段"或信息片段（如MeetingTitle、ActionItemsList）
每個字段的數據類型（如string、list、number）
如果字段包含更復雜的數據，該數據的藍圖是什么樣

當基于Pydantic模型創建對象時，Pydantic會自動**驗證**提供的數據。

如果數據不符合藍圖約定（例如在需要字符串的位置使用數字，或缺少必填字段），Pydantic將拋出錯誤。這有助于盡早發現錯誤！

我們的摘要藍圖：`SummaryResponse`模型

在meeting-minutes項目中，AI生成的最終結構化摘要的主要藍圖由名為SummaryResponse的Pydantic模型定義。

該模型設計用于容納摘要中所需的所有不同部分，如整體摘要、行動項、決策等。

我們可以在API文檔中查看SummaryResponse的預期JSON結構，特別是在/get-summary/{process_id}端點和Data Models部分。
它定義了MeetingName、SectionSummary、CriticalDeadlines、KeyItemsDecisions等字段，并規定了每個字段的內容。

讓我們看看后端代碼（backend/app/transcript_processor.py）中如何使用Pydantic模型逐步構建這個結構。

最小構件：`Block`模型

摘要是由多個部分組成的，每個部分包含單獨的"塊"內容——如單個行動項、單個決策點或摘要文本段落。

以下是Block的Pydantic模型：

# backend/app/transcript_processor.py（簡化片段）
from pydantic import BaseModel # 需要導入BaseModel來創建Pydantic模型class Block(BaseModel):"""表示摘要部分中的內容塊"""id: str      # 該塊的唯一標識符（字符串）type: str    # 塊的類型（如"text"、"action"、"decision"）（字符串）content: str # 塊的實際文本內容（字符串）color: str   # 顏色提示，可能用于UI顯示（字符串）# 符合此藍圖的數據示例：
# {"id": "123", "type": "action", "content": "Email report to John", "color": "yellow"}

說明：

class Block(BaseModel): 這行告訴Pydantic我們正在定義一個名為Block的模型，它繼承自BaseModel，從而獲得Pydantic的所有功能
id: str：定義名為id的字段，指定其必須是str（字符串）
type: str、content: str、color: str：類似地定義其他必填字符串字段
文檔字符串"""表示摘要部分中的內容塊..."""幫助解釋模型的用途

如果嘗試創建像Block(id=123, type="text", content="...", color="...")這樣的Block對象，Pydantic會報錯，因為id是數字（123），而藍圖規定必須是字符串（str）。

組合塊：`Section`模型

多個Block對象的集合構成摘要中的一個Section（如"Immediate Action Items"部分或"Key Items Decisions"部分）。

以下是Section的Pydantic模型：

# backend/app/transcript_processor.py（簡化片段）
from pydantic import BaseModel
from typing import List # 需要用來指定列表類型# （Block模型定義在此處）
# class Block(BaseModel): ...class Section(BaseModel):"""表示會議摘要中的一個部分"""title: str      # 部分的標題（如"Action Items"）（字符串）blocks: List[Block] # Block對象列表（Block列表）# 符合此藍圖的數據示例：
# {
#   "title": "Immediate Action Items",
#   "blocks": [
#     {"id": "1", "type": "action", "content": "Email report", "color": "yellow"},
#     {"id": "2", "type": "action", "content": "Schedule meeting", "color": "yellow"}
#   ]
# }

說明：

class Section(BaseModel): 定義Section模型
title: str：部分標題的必填字符串字段
blocks: List[Block]：這里使用Block模型。該字段是一個List（標準Python類型提示），列表中的項必須是Block對象（符合Block藍圖的數據）

因此，Section必須有一個字符串標題和一個列表，列表中的每個項都必須符合Block藍圖。

完整摘要藍圖：`SummaryResponse`模型

最后，完整的摘要輸出由SummaryResponse模型表示。該模型組合了多個Section模型，每個模型表示從轉錄文本中提取的不同類別信息。

以下是backend/app/transcript_processor.py中SummaryResponse的（稍作簡化的）Pydantic模型：

# backend/app/transcript_processor.py（簡化片段）
from pydantic import BaseModel
from typing import List # 仍然需要用于部分內部的列表# （Block和Section模型定義在此處）
# class Block(BaseModel): ...
# class Section(BaseModel): ...class SummaryResponse(BaseModel):"""表示基于轉錄文本部分的會議摘要響應"""MeetingName : strSectionSummary : Section          # 整體摘要部分CriticalDeadlines: Section        # 截止日期部分KeyItemsDecisions: Section        # 決策部分ImmediateActionItems: Section     # 行動項部分NextSteps: Section                # 后續步驟部分OtherImportantPoints: Section     # 其他要點部分ClosingRemarks: Section           # 結束語部分# 符合此藍圖的數據示例：
# {
#   "MeetingName": "Q3 Planning",
#   "SectionSummary": { ... 符合Section模型的數據 ... },
#   "CriticalDeadlines": { ... 符合Section模型的數據 ... },
#   "KeyItemsDecisions": { ... 符合Section模型的數據 ... },
#   "ImmediateActionItems": { ... 符合Section模型的數據 ... },
#   "NextSteps": { ... 符合Section模型的數據 ... },
#   "OtherImportantPoints": { ... 符合Section模型的數據 ... },
#   "ClosingRemarks": { ... 符合Section模型的數據 ... }
# }

說明：

class SummaryResponse(BaseModel): 定義主摘要模型
MeetingName: str：會議名稱的簡單字符串字段
SectionSummary: Section、CriticalDeadlines: Section等：這些字段指定每個鍵必須包含完全匹配我們之前定義的Section藍圖的數據

因此，SummaryResponse藍圖要求一個會議名稱（字符串）和七個特定部分

每個部分都必須有標題（字符串）和塊列表，每個塊必須有id、類型、內容和顏色（都是字符串）。這為摘要數據創建了嚴格的多層結構。

🎢后端如何使用Pydantic模型

現在我們有了這些藍圖，后端如何應用它們？

定義API預期： 如第1章：后端API網關所示，像TranscriptRequest這樣的Pydantic模型用于定義API端點接收數據的格式。FastAPI自動讀取這些模型，將其用于請求驗證和生成API文檔
指導AI輸出（使用Pydantic-AI）： 我們后端的關鍵部分是TranscriptProcessor（詳見第4章：轉錄處理邏輯和第5章：AI模型交互（Pydantic-AI代理））。該處理器使用pydantic-ai庫中的Agent，專門配置為生成符合SummaryResponse Pydantic模型的數據
- pydantic-ai庫幫助彌合AI模型的文本輸出與我們期望的結構化數據之間的差距。它告訴AI：“生成類似JSON的文本，并確保該JSON符合特定的SummaryResponse結構。”如果AI的初始輸出不完全匹配，pydantic-ai代理通常會嘗試修復或重試，直到獲得有效數據
驗證： 當TranscriptProcessor獲取AI的輸出時，會立即將其解析為SummaryResponse Pydantic對象。如果AI生成的數據無效（不符合SummaryResponse藍圖），Pydantic會立即拋出驗證錯誤。這防止了錯誤數據進入系統或保存到數據庫管理
序列化： 后端將摘要數據作為SummaryResponse Pydantic對象后，可以輕松轉換為JSON格式通過API網關發送回前端。Pydantic有內置方法（model_dump_json()）實現此功能。FastAPI在從端點函數返回Pydantic模型對象時也會自動處理

下面是展示AI處理和Pydantic作用的簡化流程：

在這里插入圖片描述

該流程圖展示了AI的原始文本輸出如何

通過Pydantic-AI代理適應SummaryResponse藍圖

創建結構化Pydantic對象

FastAPI隨后可以輕松將其轉換為JSON并發送至前端。

使用Pydantic模型的優勢

使用Pydantic模型定義數據結構具有顯著優勢：

定義清晰： 模型代碼明確定義了數據的預期形態和類型
自動驗證： Pydantic根據藍圖檢查出入數據，盡早捕獲錯誤
提升代碼可讀性： 使用明確定義的Pydantic對象的代碼比傳遞不確定內容的字典更易理解
輕松序列化/反序列化： Python對象與JSON之間的轉換（API和數據庫常用）由Pydantic和FastAPI自動處理
自文檔化： Pydantic模型直接貢獻于FastAPI在/docs生成的交互式API文檔，使文檔更準確且易于維護

通過定義SummaryResponse及其嵌套的Section和Block模型，我們為AI生成的摘要創建了健壯且可預測的格式

使后端工作更輕松，并確保前端始終接收可處理的數據。

結論

在本章中，我們探討了meeting-minutes項目如何使用Pydantic庫定義AI生成會議摘要的結構。

我們了解了像Block、Section和頂層SummaryResponse這樣的模型如何作為藍圖來規定必填字段和數據類型。（即底層調用Pydantic庫）

使用Pydantic可以確保摘要數據始終遵循可預測的格式，這對驗證、后端代碼的易用性以及通過后端API網關與前端可靠通信至關重要（如第1章所述）。
這也直接關聯到第2章描述的API文檔中的數據格式規范。

現在我們已經理解了摘要的預期輸出結構，接下來的問題是：如何實際處理原始會議轉錄文本來輸入生成符合SummaryResponse藍圖的數據？

這涉及轉錄分析的核心邏輯。

在下一章中，我們將深入探討轉錄處理邏輯，它負責獲取原始文本輸入并生成由Pydantic模型定義的結構化數據。

第4章：轉錄處理邏輯

補充

Pydantic庫的底層調用關系

在智能創作助手的模型架構中，Block、Section和SummaryResponse等模型通常基于Pydantic庫實現數據驗證和序列化。Pydantic提供了類型注解、數據校驗和自動生成文檔的功能，適合構建結構化數據模型。

模型與Pydantic的關系

Block、Section等組件通常定義為Pydantic的BaseModel子類，利用其類型系統確保輸入輸出的數據結構符合預期。例如：

from pydantic import BaseModelclass Block(BaseModel):content: strtype: str

SummaryResponse作為頂層響應模型，可能嵌套其他Pydantic模型，形成層次化結構。Pydantic的嵌套模型能力支持復雜數據關系的描述和驗證。

Pydantic的核心優勢

數據驗證：運行時自動檢查字段類型和約束條件，如字符串長度、數值范圍等。
序列化：提供model_dump()和model_dump_json()等方法，方便與JSON等格式互轉。
文檔生成：結合類型注解自動生成OpenAPI/Swagger文檔，適合API開發場景。

其他可能的底層依賴

雖然Pydantic是常見選擇，但具體實現可能因框架而異。FastAPI等框架默認集成Pydantic，而其他系統可能采用自定義驗證邏輯或替代庫（如marshmallow）。

需結合具體代碼庫或文檔確認實際調用關系。

marshmallow庫

marshmallow是一個Python庫，用于將復雜的數據類型（如對象、字典）與簡單數據類型（如JSON）相互轉換，常用于API開發中的數據驗證和序列化。

通俗講：它像數據的“翻譯官”，確保輸入輸出格式正確且干凈。

marshmallow庫 vs Pydantic庫

功能定位

marshmallow：專注于數據序列化/反序列化，適合API請求/響應數據的格式轉換。
Pydantic：強調數據驗證和類型提示，適合構建數據模型并自動處理類型轉換。

典型場景

marshmallow：常見于Flask等框架的JSON數據處理。更輕量
Pydantic：多用于FastAPI的請求參數驗證和配置管理。更多功能

開發體驗

marshmallow：需顯式定義序列化規則。
Pydantic：利用Python類型注解自動生成驗證邏輯。

一般方案

優先使用 Pydantic 的完整功能鏈（如 BaseModel + validator + json()），減少依賴混合庫帶來的維護成本。

example:

若需 Marshmallow 的特定功能（如自定義驗證邏輯），可單獨在部分邏輯中使用。

Pydantic 的 validator 裝飾器通常能滿足類似需求。