[Meetily后端框架] 配置指南 | 后端API网关 | API文档体系

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

docs：会议纪要管理系统

本项目是一个专门用于**处理会议记录**的后端系统。
系统接收会议文本内容，利用先进的AI模型自动识别关键信息，包括行动项、决策内容以及截止期限。
处理结果将存入数据库并格式化为清晰的结构化的摘要报告。系统整合了*音频转文字*工具链，并提供自动化部署脚本实现后端服务的快速搭建与运行。

系统架构

结构化处理会议内容后，即可通过mcp协议 传回llm了

章节目录

1. 后端API网关
   
2. API文档
   
3. 摘要数据结构（Pydantic模型）
   
4. 文本处理逻辑
   
5. AI模型交互层（Pydantic-AI代理）
   
6. 数据库管理
   
7. Whisper语音转写服务
   
8. 后端服务管理脚本
   

Meetily AI会议助手配置指南

Meetily是一款本地化AI会议助手，支持实时音频采集、语音转写和智能摘要生成，具备以下核心优势：

• 🔒 隐私优先：所有处理在本地设备完成
• 💰 经济高效：采用开源AI模型替代付费API
• 🛠️ 灵活部署：支持Windows/macOS双平台离线运行
• 🧠 智能分析：内置知识图谱实现语义检索

二、系统架构

核心组件

1. 音频采集服务

   • Rust/Python双栈实现
   • 支持麦克风/系统音频双通道采集

2. 转录引擎

   • 基于Whisper.cpp本地引擎
   • 支持GPU加速（tiny->large-v3多尺寸模型）

3. 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模型选择

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

五、LLM集成

配置要点：

1. 在backend/config.yaml中设置API密钥
2. 启用多模型回退机制
3. 验证函数调用支持：

   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   # 跨平台构建脚本

贡献流程

1. Fork项目仓库
2. 创建特性分支
3. 提交PR时包含：
   • 测试用例
   • API变更文档
   • 类型注解说明

八、扩展配置

知识图谱启用

# config.yaml
knowledge_graph:
  enable: true
  storage_path: /var/meetily/kg
  indexing_interval: 300 # 秒

Obsidian集成

1. 安装社区插件Meetily Bridge
2. 配置同步路径：

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

提示：完整开发文档可通过meetily-docs --web启动本地文档服务器查看

本教程持续更新，建议通过brew upgrade meetily获取最新版本。

第一章：后端API网关

欢迎来到meeting-minutes后端部分的首个章节！

我们将深入探索该项目的后台运作机制。后端如同系统的"大脑"，承担着处理会议转录、生成行动项、数据存储等核心任务。

本章将聚焦系统的入口组件——后端API网关。

API网关解决的问题

想象我们身处大型企业总部，访客需要办理各类事务：会面、快递、求职、设备维护等。所有流程都始于前台接待，其核心价值在于：

1. 作为唯一入口点，无需知晓内部办公室分布
2. 精准理解需求并引导至对应部门
3. 高效处理登记、签收等标准化流程

在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 FastAPI

app = FastAPI(
    title="会议摘要生成API",
    description="处理与生成会议转录摘要的接口服务",
    version="1.0.0"
)

2. 数据模型定义

from pydantic import BaseModel

class 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网关作为系统的神经中枢，主要承担：

1. 统一接入：聚合所有服务端点
2. 流量调度：智能路由请求
3. 异步处理：解耦耗时操作
4. 状态管理：维护处理生命周期
5. 异常处理：统一错误响应机制

通过FastAPI的异步特性与后台任务管理，实现了高并发下的请求吞吐与资源优化。

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

下一章将详解API文档生成与管理机制。

第二章：API文档体系

第二章：API文档体系

在第一章：后端API网关中，我们了解到API网关是后端系统的入口枢纽，如同企业大楼的前台接待处。

本章将揭示如何通过API文档体系，清晰定义这个"数字前台"的服务目录。

API文档的价值定位

假设我们正在构建会议纪要系统的前端界面，需要向后端提交转录文本。

此时必须明确以下问题：

• 请求地址是/submit还是/process-transcript？
• 应该使用GET还是POST方法？
• 请求体需要包含哪些字段？采用JSON还是XML格式？
• 响应数据包含处理ID还是直接返回摘要？

API文档正是解决这些疑问的开发者手册，定义了前后端交互的契约规范。

其核心作用如同餐厅菜单：

API文档要素

完整的API文档应包含：

项目文档实现方式

本项目采用双轨制文档体系：

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

路径参数

响应状态码

2. 动态交互文档（/docs）

通过FastAPI自动生成的Swagger UI界面，访问http://localhost:5167/docs即可获得：

该文档具备三大特性：

1. 实时同步：随代码变更自动更新
2. 交互测试：支持在线发送测试请求
3. 结构可视化：展示嵌套数据模型

文档生成原理

动态文档的生成基于代码注解：

from fastapi import FastAPI
from pydantic import BaseModel

class TranscriptRequest(BaseModel):
    """转录处理请求数据结构"""
    text: str
    model: str = "claude"

app = FastAPI(
    title="智能会议摘要系统",
    description="基于AI的会议内容分析服务"
)

@app.post("/process-transcript")
async def handle_transcript(req: TranscriptRequest):
    """接收转录文本并启动处理流程"""
    return {"process_id": "123"}

FastAPI通过装饰器@app.post捕获端点信息，结合Pydantic模型定义生成文档结构。

函数文档字符串（docstring）将直接呈现在交互界面上。

总结

1. 契约定义：API文档明确前后端交互规则
2. 双轨体系：静态文档提供完整配置说明，动态文档支持实时测试
3. 自描述性：代码即文档，通过类型注解自动生成规范
4. 开发者友好：降低接入成本，提升协作效率

了解了数据交互规范后，我们将深入第三章：摘要数据结构（Pydantic模型），解析系统核心数据结构的定义与校验机制。