当前位置：首页 > news >正文

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

news 来源：原创 2025/6/28 15:49:00

链接: 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"}