[Meetily后端框架] 配置指南 | 后端API網關

鏈接: https://github.com/Zackriya-Solutions/meeting-minutes

在這里插入圖片描述

docs：會議紀要管理系統

本項目是一個專門用于**處理會議記錄**的后端系統。
系統接收會議文本內容，利用先進的AI模型自動識別關鍵信息，包括行動項、決策內容以及截止期限。
處理結果將存入數據庫并格式化為清晰的結構化的摘要報告。系統整合了*音頻轉文字*工具鏈，并提供自動化部署腳本實現后端服務的快速搭建與運行。

系統架構

在這里插入圖片描述
結構化處理會議內容后，即可通過mcp協議傳回llm了

章節目錄

后端API網關
API文檔
摘要數據結構（Pydantic模型）
文本處理邏輯
AI模型交互層（Pydantic-AI代理）
數據庫管理
Whisper語音轉寫服務
后端服務管理腳本

Meetily AI會議助手配置指南

Meetily是一款本地化AI會議助手，支持實時音頻采集、語音轉寫和智能摘要生成，具備以下核心優勢：

🔒 隱私優先：所有處理在本地設備完成
💰 經濟高效：采用開源AI模型替代付費API
🛠? 靈活部署：支持Windows/macOS雙平臺離線運行
🧠 智能分析：內置知識圖譜實現語義檢索

二、系統架構

在這里插入圖片描述

核心組件

音頻采集服務
- Rust/Python雙棧實現
- 支持麥克風/系統音頻雙通道采集
轉錄引擎
- 基于Whisper.cpp本地引擎
- 支持GPU加速（tiny->large-v3多尺寸模型）
LLM編排器
- 統一接口適配多模型提供商
- 自動分塊重疊處理（默認分塊4K/重疊1K）

三、安裝部署

先決條件

Node.js 18+
Python 3.10+
FFmpeg
Rust 1.65+（可選特性）
Cmake 3.22+

Windows部署

前端安裝

# 方式1：EXE安裝（推薦）
meetily-frontend_0.0.4_x64-setup.exe# 方式2：MSI安裝
meetily-frontend_0.0.4_x64_en-US.msi# 安全警告處理
右鍵安裝包 > 屬性 > 勾選"解除鎖定"

后端部署

git clone https://github.com/Zackriya-Solutions/meeting-minutes
cd meeting-minutes/backend# 手動部署
.\build_whisper.cmd
.\start_with_output.ps1# Docker部署
.\docker-build.bat

在這里插入圖片描述

四、模型配置

Whisper模型選擇

模型類型	適用場景	示例型號
標準模型	`平衡精度與速度`	small, medium
英語優化	純英文環境加速	small.en, medium.en
量化模型	`存儲空間`受限	tiny-q5_1, base-q5_1
高級模型	專業場景需求	large-v3-turbo

# 模型下載命令
meetily-download-model small

五、LLM集成

在這里插入圖片描述

配置要點：

在backend/config.yaml中設置API密鑰
啟用多模型回退機制

驗證函數調用支持：

curl http://localhost:5167/validate-llm

六、故障排除

后端問題

# 端口占用檢查
lsof -i :8178 && lsof -i :5167# FFmpeg驗證
ffmpeg -version | grep 'configuration'# 日志查看
tail -f $(brew --prefix)/var/log/meetily-backend.log

前端問題

# 連接測試
nc -zv localhost 5167# 權限重置
xattr -cr /Applications/meetily-frontend.app

七、開發指南

代碼結構

meeting-minutes/
├── frontend/          # Tauri+Next.js前端
├── backend/           # FastAPI后端
│   ├── whisper-server-package/
│   └── transcript_processor.py
└── docker-build.bat   # 跨平臺構建腳本

貢獻流程

Fork項目倉庫
創建特性分支
提交PR時包含：
- 測試用例
- API變更文檔
- 類型注解說明

八、擴展配置

知識圖譜啟用

# config.yaml
knowledge_graph:enable: truestorage_path: /var/meetily/kgindexing_interval: 300 # 秒

Obsidian集成

安裝社區插件Meetily Bridge

配置同步路徑：

{"vault_path": "/Users/<username>/Documents/Obsidian","sync_interval": 600
}

提示：完整開發文檔可通過meetily-docs --web啟動本地文檔服務器查看

本教程持續更新，建議通過brew upgrade meetily獲取最新版本。

第一章：后端API網關

歡迎來到meeting-minutes后端部分的首個章節！

我們將深入探索該項目的后臺運作機制。后端如同系統的"大腦"，承擔著處理會議轉錄、生成行動項、數據存儲等核心任務。

本章將聚焦系統的入口組件——后端API網關。

API網關解決的問題

想象我們身處大型企業總部，訪客需要辦理各類事務：會面、快遞、求職、設備維護等。所有流程都始于前臺接待，其核心價值在于：

作為唯一入口點，無需知曉內部辦公室分布
精準理解需求并引導至對應部門
高效處理登記、簽收等標準化流程

在meeting-minutes系統中，后端服務器如同企業大樓，前端應用（網頁/桌面端）則是需要服務的訪客。

前端需要與后端進行多種交互：

提交新會議轉錄文本
獲取處理完成的會議摘要
查詢歷史會議記錄
保存用戶配置參數

若無統一入口，前端將不知如何定向請求。

這正是后端API網關的價值所在——它如同數字前臺，接收所有前端請求并路由至對應處理模塊。

API網關的核心職能

該組件承擔四大核心角色：
在這里插入圖片描述

技術實現基于Python的FastAPI框架，通過定義端點（endpoints）提供服務接入。

實戰案例：轉錄處理流程

以前端提交會議轉錄為例，演示網關工作流程。根據API文檔，處理端點地址為/process-transcript，采用POST方法。

可通過curl命令模擬請求：

curl -X POST \http://localhost:5167/process-transcript \-H "Content-Type: application/json" \-d '{"text": "本次會議討論季度目標...","model": "claude","model_name": "claude-3-5-sonnet-latest","meeting_id": "dummy-123"
}'

參數解析：

-X POST：指定POST請求方法
http://localhost:5167/process-transcript：網關地址與端點路徑
-H：聲明JSON數據格式
-d：傳輸的JSON有效載荷

后端代碼解析

查看backend/app/main.py中的網關實現：

1. FastAPI應用初始化

from fastapi import FastAPIapp = FastAPI(title="會議摘要生成API",description="處理與生成會議轉錄摘要的接口服務",version="1.0.0"
)

2. 數據模型定義

from pydantic import BaseModelclass TranscriptRequest(BaseModel):text: str  # 轉錄文本model: str  # AI模型類型model_name: str  # 具體模型版本meeting_id: str  # 會議唯一標識chunk_size: int | None = 5000  # 文本分塊大小overlap: int | None = 1000  # 分塊重疊區間

3. 端點邏輯實現

@app.post("/process-transcript")
async def process_transcript_api(transcript: TranscriptRequest, background_tasks: BackgroundTasks
):try:# 創建處理記錄process_id = await db.create_process(transcript.meeting_id)# 啟動后臺任務background_tasks.add_task(process_transcript_background,process_id,transcript)# 立即返回響應return JSONResponse({"message": "處理任務已啟動","process_id": process_id})except Exception as e:raise HTTPException(status_code=500, detail=str(e))

4. 后臺任務處理

async def process_transcript_background(process_id: str, transcript: TranscriptRequest):"""模擬異步處理任務"""await asyncio.sleep(5)  # 模擬AI處理耗時await db.update_process(process_id, status="completed",result='{"MeetingName": "測試會議", "SectionSummary": {...}}')

系統交互流程圖

在這里插入圖片描述

總結

后端API網關作為系統的神經中樞，主要承擔：

統一接入：聚合所有服務端點
流量調度：智能路由請求
異步處理：解耦耗時操作
狀態管理：維護處理生命周期
異常處理：統一錯誤響應機制

通過FastAPI的異步特性與后臺任務管理，實現了高并發下的請求吞吐與資源優化。

了解端點功能后，如何掌握完整的API規范？

下一章將詳解API文檔生成與管理機制。

第二章：API文檔體系

在第一章：后端API網關中，我們了解到API網關是后端系統的入口樞紐，如同企業大樓的前臺接待處。

本章將揭示如何通過API文檔體系，清晰定義這個"數字前臺"的服務目錄。

API文檔的價值定位

假設我們正在構建會議紀要系統的前端界面，需要向后端提交轉錄文本。

此時必須明確以下問題：

請求地址是/submit還是/process-transcript？
應該使用GET還是POST方法？
請求體需要包含哪些字段？采用JSON還是XML格式？
響應數據包含處理ID還是直接返回摘要？

API文檔正是解決這些疑問的開發者手冊，定義了前后端交互的契約規范。

其核心作用如同餐廳菜單：
在這里插入圖片描述

API文檔要素

完整的API文檔應包含：

要素類別	說明	示例
服務端點	接口訪問路徑	`/process-transcript`
HTTP方法	請求類型（POST/GET等）	POST
請求格式	數據結構與必填字段	JSON包含text/model等字段
響應格式	返回數據結構與狀態碼	200成功，202處理中，404未找到
鑒權方式	身份驗證機制	本項目暫無需鑒權

項目文檔實現方式

本項目采用雙軌制文檔體系：

1. 靜態文檔文件（API_DOCUMENTATION.md）

位于后端目錄的Markdown文件，提供完整的配置說明：

# Meetily API 文檔## 基礎配置
```http
http://localhost:5167

端點說明

1. 處理轉錄文本

端點路徑：/process-transcript
請求方法：POST
內容類型：application/json

請求體示例

{"text": "會議討論三季度目標...","model": "ollama","model_name": "qwen2.5:14b","chunk_size": 40000
}

響應示例

{"process_id": "3fa85f64-5717-4562","message": "處理任務已啟動"
}

3. 獲取摘要

端點路徑：/get-summary/{process_id}
請求方法：GET

路徑參數

參數	類型	必填	說明
process_id	字符串	是	處理任務`唯一標識`

響應狀態碼

狀態碼	說明
200	摘要生成完成
202	處理進行中
404	任務ID不存在

2. 動態交互文檔（/docs）

通過FastAPI自動生成的Swagger UI界面，訪問http://localhost:5167/docs即可獲得：

在這里插入圖片描述

該文檔具備三大特性：

實時同步：隨代碼變更自動更新
交互測試：支持在線發送測試請求
結構可視化：展示嵌套數據模型

文檔生成原理

動態文檔的生成基于代碼注解：

from fastapi import FastAPI
from pydantic import BaseModelclass TranscriptRequest(BaseModel):"""轉錄處理請求數據結構"""text: strmodel: str = "claude"app = FastAPI(title="智能會議摘要系統",description="基于AI的會議內容分析服務"
)@app.post("/process-transcript")
async def handle_transcript(req: TranscriptRequest):"""接收轉錄文本并啟動處理流程"""return {"process_id": "123"}