Meetily 后端 API 实战指南基于 FastAPI 的会议纪要生成服务从配置到调用【免费下载链接】meetilyPrivacy first, AI meeting assistant with 4x faster Parakeet/Whisper live transcription, speaker diarization, and Ollama summarization built on Rust. 100% local processing. no cloud required. Meetily (Meetly Ai - https://meetily.ai) is the #1 Self-hosted, Open-source Ai meeting note taker for macOS Windows. Understand How to write meeting minutes项目地址: https://gitcode.com/GitHub_Trending/me/meetily本指南系统讲解 Meetily 项目后端 Python 服务的完整 API 能力涵盖环境搭建、数据库初始化、服务启动、转录文本分块处理、结构化会议纪要生成与状态轮询等全流程。读完本文你将掌握process-transcript、get-summary等核心端点的请求与响应契约、Block/Section 数据模型的内部约定并能基于仓库自带的 Python 工作流脚本快速接入这套会议摘要 API。一、服务定位与整体架构Meetily 的 Python 后端是一个基于 FastAPI 构建的轻量级 API 服务核心职责是接收会议转录文本调用 AI 模型Claude、Groq、OpenAI 或本地 Ollama生成结构化会议纪要并将处理过程与结果持久化到本地 SQLite 数据库。它面向的典型场景是Whisper 等引擎实时产出转录文本后由前端或外部脚本提交给本服务完成智能摘要随后前端以轮询方式获取结构化摘要结果用于渲染。从源码结构看服务由三个核心模块构成模块文件职责应用入口backend/app/main.pyFastAPI 应用、路由定义、后台任务调度、CORS 配置数据处理backend/app/transcript_processor.py转录文本分块、AI Agent 调用、结构化输出校验数据持久化backend/app/db.pySQLite 表管理、进程状态跟踪、配置与 API Key 存储另有 backend/app/schema_validator.py 在启动时对数据库表结构做自动校验与缺失列补全保证旧库平滑升级。官方 API 文档位于仓库 backend/API_DOCUMENTATION.md本文以其为骨架展开并深入对应源码讲解底层实现原理。二、环境准备与安装2.1 系统要求运行本服务需要满足Python 3.8 或更高版本pipPython 包安装器SQLite 3足够的磁盘空间用于存放数据库与转录文本数据2.2 环境变量配置在backend目录下创建.env文件写入以下变量# API Keys ANTHROPIC_API_KEYyour_anthropic_api_key # Required for Claude model GROQ_API_KEYyour_groq_api_key # Optional, for Groq model # Database Configuration DB_PATH./meetings.db # SQLite database path # Server Configuration HOST0.0.0.0 # Server host PORT5167 # Server port # Processing Configuration CHUNK_SIZE5000 # Default chunk size for processing CHUNK_OVERLAP1000 # Default overlap between chunks需要说明的几点源码级细节数据库路径官方文档将环境变量写作DB_PATH但当前 backend/app/db.py 中DatabaseManager实际读取的是DATABASE_PATH未设置时默认使用meeting_minutes.db。仓库根目录还提供了 backend/temp.env 模板含ANTHROPIC_API_KEY、GROQ_API_KEY、OPENAI_API_KEY三个占位键与一键配置脚本 backend/set_env.sh脚本会从系统环境读取已有 Key 或交互式提示输入并写入.env。HOST/PORT源码默认监听0.0.0.0:5167见 backend/app/main.py 的 uvicorn 启动配置.env中的HOST/PORT需在启动命令中显式传入才会生效。CHUNK_SIZE/CHUNK_OVERLAP.env中的这两个变量在 transcript_processor.py 中并未被读取实际分块参数由 API 请求体中的chunk_size与overlap字段控制默认值 5000/1000 定义于 main.py 的TranscriptRequest模型中。2.3 安装步骤# 1. 创建并激活虚拟环境 python -m venv venv source venv/bin/activate # Windows 下使用: venv\Scripts\activate # 2. 安装依赖 pip install -r requirements.txt官方文档所列依赖包为pydantic、pydantic-ai、pandas、devtools、chromadb、python-dotenv、fastapi、uvicorn、python-multipart、aiosqlite。以当前仓库 backend/requirements.txt 为准实际锁定版本如下pydantic-ai0.2.15 pydantic2.11.5 pandas2.2.3 devtools0.12.2 python-dotenv1.1.0 fastapi0.115.9 uvicorn0.34.0 python-multipart0.0.20 aiosqlite0.21.0 ollama0.5.2与文档相比实际依赖已升级pydantic-ai到 0.2.x、新增ollama客户端包用于本地模型调用且当前版本列表已不含chromadb。python-multipart是 FastAPI 处理表单/文件上传的必需依赖ollama包支撑 Ollama 本地模型的流式调用。2.4 初始化数据库python -c from app.db import init_db; import asyncio; asyncio.run(init_db())注意这条命令来自官方文档但当前源码中的初始化入口已演化为DatabaseManager类。在 backend/app/db.py 中DatabaseManager.__init__会直接执行_legacy_init_db()建表与schema_validator.validate_schema()校验补列因此实际初始化方式是在服务启动时自动完成无需手动执行单独命令。如果你需要手动初始化可参考python -c from db import DatabaseManager; DatabaseManager()建表逻辑位于 backend/app/db.py会创建以下数据表meetings会议主表id、title、created_at、updated_at、folder_pathtranscripts逐段转录文本含audio_start_time、audio_end_time、duration三个录音相对时间戳用于音文同步播放summary_processes摘要处理进程状态表status、result、error、start_time、end_time、chunk_count、processing_time 等transcript_chunks整段转录原始文本与模型参数快照settings摘要模型配置与各供应商 API Keytranscript_settings转录引擎配置localWhisper/deepgram/elevenLabs/groq/openai2.5 启动服务器uvicorn app.main:app --host 0.0.0.0 --port 5167 --reload服务启动后API 根地址http://localhost:5167FastAPI 自动生成的交互式文档http://localhost:5167/docs源码中FastAPI(titleMeeting Summarizer API, ...)定义于 backend/app/main.py若直接运行python app/main.py参考 backend/start_python_backend.cmd 的启动方式main 入口会调用uvicorn.run(main:app, host0.0.0.0, port5167, reloadTrue)效果等价。更完整的部署方式含 Docker 与 Whisper 服务编排见 backend/README.md。三、项目结构backend/ ├── app/ │ ├── __init__.py │ ├── main.py # Main FastAPI application │ ├── db.py # Database operations │ ├── schema_validator.py # Database schema validation auto-fix │ └── transcript_processor.py # Transcript processing logic ├── examples/ │ └── run_summary_workflow.py # 端到端调用示例脚本 ├── requirements.txt # Python dependencies ├── temp.env # 环境变量模板 ├── set_env.sh # 环境变量配置脚本 └── meeting_minutes.db # SQLite database (启动后生成)四、API 概览Base URLhttp://localhost:5167认证目前所有端点均无需认证即可访问官方文档明确说明 Currently, no authentication is required for API endpoints。不过在 main.py 的后台处理逻辑中对claude/groq/openai三类云端供应商做了二次校验若数据库中未配置对应 API Key任务会被标记为失败并返回 API key not configured 的明确错误。也就是说接口层无认证但调用云端模型前必须有有效 Key。CORS为方便本地前后端联调服务通过CORSMiddleware放行了所有来源、方法与请求头预检请求缓存 1 小时见 backend/app/main.py。五、核心端点详解5.1 Process Transcript —— 直接提交转录文本Endpoint:/process-transcriptMethod:POSTContent-Type:application/json提交一段转录文本服务立即返回处理 ID 并异步执行摘要生成。请求体{ text: string, // Required: The transcript text model: string, // Required: AI model to use (e.g., ollama) model_name: string, // Required: Model version (e.g., qwen2.5:14b) chunk_size: 40000, // Optional: Size of text chunks (default: 5000) overlap: 1000 // Optional: Overlap between chunks (default: 1000) }对照源码 backend/app/main.py 中的TranscriptRequest模型实际请求体还包含两个字段meeting_id必填会议 ID用于关联会议记录。响应返回的process_id在实现中就是这个meeting_id见下文。custom_prompt可选自定义摘要提示词默认值为Generate a summary of the meeting transcript.会被注入到每个分块的 AI 提示中。chunk_size与overlap的参数校验在SummaryProcessor.process_transcript中完成backend/app/main.pychunk_size必须为正数overlap必须非负且小于chunk_size若overlap chunk_size会被自动调整为chunk_size - 1以保证步长为正。响应{ process_id: string, message: Processing started }后台处理流程backend/app/main.py先通过db.create_process(meeting_id)在summary_processes表中创建/重置状态为PENDING的进程记录再调用db.save_transcript将原始文本与模型参数快照写入transcript_chunks表最后通过 FastAPI 的BackgroundTasks将摘要任务放入后台线程执行接口立即返回不阻塞调用方。5.2 Upload Transcript —— 上传转录文件Endpoint:/upload-transcriptMethod:POSTContent-Type:multipart/form-data官方文档记载此端点提供与/process-transcript相同的功能但以文件上传替代原始文本参数如下参数类型必填说明fileFile是要上传的转录文件modelString否AI 模型默认 claudemodel_nameString否具体模型版本默认 claude-3-5-sonnet-latestchunk_sizeInteger否文本分块大小默认 5000overlapInteger否分块重叠默认 1000响应同样为{ process_id: string, message: Processing started }重要提示经过对当前仓库源码的检索backend/app/main.py 中暂未找到/upload-transcript的路由实现该路径目前仅出现在文档中。因此该端点属于文档记载的接口契约若你依赖文件上传能力请以当前实际运行的源码为准优先使用/process-transcript提交文本或自行按文档契约补充实现。5.3 Get Summary —— 获取摘要结果Endpoint:/get-summary/{process_id}Method:GET路径参数参数类型必填说明process_idString是要查询的处理 ID这里的process_id与/process-transcript传入的meeting_id等价create_process方法直接以meeting_id作为进程主键backend/app/db.py因此轮询时使用响应返回的process_id即可。响应状态码语义CodeDescription200Success - Summary completed202Accepted - Processing in progress400Bad Request - Failed or unknown status404Not Found - Process ID not found500Internal Server Error - Server-side error响应体{ status: string, // completed, processing, error meetingName: string, // Name of the meeting (null if not available) process_id: string, // Process ID data: { // Summary data (null if not completed) MeetingName: string, SectionSummary: { title: string, blocks: [ { id: string, type: string, content: string, color: string } ] }, CriticalDeadlines: { title: string, blocks: [] }, KeyItemsDecisions: { title: string, blocks: [] }, ImmediateActionItems: { title: string, blocks: [] }, NextSteps: { title: string, blocks: [] }, OtherImportantPoints: { title: string, blocks: [] }, ClosingRemarks: { title: string, blocks: [] } }, start: string, // Start time in ISO format (null if not started) end: string, // End time in ISO format (null if not completed) error: string // Error message if status is error }对照 backend/app/main.py 的get_summary实现响应细节如下实际响应字段为meeting_id而非文档示例中的process_id其余字段一致状态映射PENDING/processing/started统一归一为processing并返回 202completed返回 200失败返回 400 且data置空摘要数据会做一次前端适配转换将后端各 Section 标题转为 snake_case 键如Session Summary→session_summary同名 Section 自动追加索引后缀防覆盖并额外输出_section_order数组以保持前端渲染顺序backend/app/main.py文档示例中的SectionSummary等键名取自早期版本约定当前源码生成的摘要结构以 transcript_processor.py 中的SummaryResponse模型为准见第六节。5.4 扩展端点源码已实现文档未覆盖当前源码在文档三个端点之外还实现了一组会议管理端点均位于 backend/app/main.py可用于完整的会议记录生命周期管理端点方法功能/get-meetingsGET获取全部会议列表id、title、created_at/get-meeting/{meeting_id}GET获取会议详情及全部转录段落/save-transcriptPOST保存转录段落含音文同步时间戳不触发摘要/save-meeting-titlePOST更新会议标题/delete-meetingPOST删除会议及其全部关联数据按外键顺序级联清理/save-meeting-summaryPOST手动保存/更新会议摘要/search-transcriptsPOST基于LIKE的转录全文检索返回匹配上下文片段±100 字符/get-model-config、/save-model-configGET/POST摘要模型配置读写/get-transcript-config、/save-transcript-configGET/POST转录引擎配置读写/get-api-key、/get-transcript-api-keyPOST读取指定供应商 API Key/save-model-config附带POST保存供应商 API Key六、数据模型与结构化输出约定6.1 Block —— 内容块Block是摘要内容的最小单元其 Pydantic 定义位于 backend/app/transcript_processor.py{ id: string, // Unique identifier type: string, // Type of block (text, action, decision, etc.) content: string, // Content text color: string // Color for UI display }源码将type收紧为字面量联合类型且与前端渲染能力严格对齐text普通段落bullet列表项heading1一级标题heading2二级标题color字段当前前端只使用gray次要内容灰色与空字符串默认色任何其他值都会按默认色渲染。这些约束会通过 pydantic-ai 的提示词明确告知模型见 transcript_processor.py保证输出符合前端组件预期。6.2 Section —— 摘要分区{ title: string, // Section title blocks: [ // Array of Block objects { id: string, type: string, content: string, color: string } ] }6.3 SummaryResponse —— 分块摘要的完整结构pydantic-ai 的Agent以SummaryResponse为结构化输出目标transcript_processor.py包含字段类型说明MeetingNamestr会议名称PeoplePeople参会人格式约定Title - Person Name (Role, Details)要求始终输出该分区SessionSummarySection会议摘要CriticalDeadlinesSection关键截止日期KeyItemsDecisionsSection关键事项与决策ImmediateActionItemsSection立即执行项NextStepsSection后续步骤MeetingNotesMeetingNotes会议笔记meeting_name sections 列表分块处理完成后main.py 中的process_transcript_background会将所有分块的 JSON 结果聚合为最终摘要会议名称取首个非空值各 Section 的 blocks 跨分块合并去重按 title 匹配后追加MeetingNotes.sections同步聚合并自动为每个分区补齐blocks数组避免前端渲染空指针。七、分块处理与模型适配原理7.1 分块策略TranscriptProcessor.process_transcriptbackend/app/transcript_processor.py按滑窗方式切分文本step chunk_size - overlap chunks [text[i:ichunk_size] for i in range(0, len(text), step)]即相邻分块间保留overlap长度的重复文本防止关键信息恰好被切分边界截断。每个分块独立交给 AI 模型生成一份SummaryResponse若某分块无相关分区内容如关键截止日期提示词要求模型返回空 blocks 列表而非省略字段transcript_processor.py。处理失败的分块会被跳过并记录日志不影响其余分块的结果汇总。7.2 模型供应商适配model参数支持四种供应商初始化逻辑见 transcript_processor.pymodel 值底层实现备注claudeAnthropicModelAnthropicProviderKey 存于 settings 表 anthropicApiKeygroqGroqModelGroqProviderKey 存于 settings 表 groqApiKeyopenaiOpenAIModelOpenAIProviderKey 存于 settings 表 openaiApiKeyollamaOpenAIModel指向本地兼容端点或AsyncClient流式调用见下文Ollama 本地模型的特殊逻辑OpenAI 兼容路径通过环境变量OLLAMA_HOST默认http://localhost:11434构造{host}/v1作为 OpenAI 兼容 base URLtranscript_processor.py因此 Ollama 服务需开启 OpenAI 兼容 API。分块大小自动适配当model_name以phi4或llama开头时chunk_size强制设为 10000其他模型设为 30000overlap固定 1000transcript_processor.py。这是针对本地模型上下文窗口的保守适配意味着调用方传入的chunk_size对 Ollama 会被覆盖。流式输出与 JSON Schema 约束chat_ollama_modeltranscript_processor.py使用AsyncClient.chat(..., streamTrue, formatSummaryResponse.model_json_schema())流式读取并通过model_json_schema()将结构化输出约束下发给 Ollama收到的响应再用SummaryResponse.model_validate_json校验若解析失败则返回原始字符串交由上层降级处理。云端模型claude/groq/openai则统一走agent.run(...)pydantic-ai 负责基于SummaryResponse自动生成 JSON Schema 并做重试result_retries2。7.3 多转录并发处理官方文档 Notes 中提到 The API supports concurrent processing of multiple transcripts。从实现看每次请求都会生成独立的后台任务SQLite 写入通过事务与BEGIN TRANSACTION保证一致性summary_processes表以meeting_id为键支持并发插入更新。需要留意 SQLite 的写锁特性高并发场景下建议评估写入频率。八、状态码与错误处理8.1 通用状态码CodeDescription200Success - Request completed successfully202Accepted - Processing in progress400Bad Request - Invalid request or parameters404Not Found - Process ID not found500Internal Server Error - Server-side error8.2 错误响应格式所有错误响应统一遵循以下结构{ status: error, meetingName: null, process_id: string, data: null, start: null, end: null, error: Error message describing what went wrong }实现细节backend/app/db.py错误信息写入数据库前会做换行/回车剥离并截断到 1000 字符防止日志注入任务最终状态为COMPLETED或FAILED时自动记录end_time。常见的可预期失败场景云端供应商未配置 API Key → 任务状态置为failedget-summary返回 400转录文本为空 → 后台任务直接抛出ValueError转录文本超过 10MB →save_transcript拒绝写入backend/app/db.py查询不存在的 meeting_id → 返回 404。九、完整调用示例9.1 curl 快速验证# 1. 上传并处理转录文件注意见 5.2 节提示当前源码未实现该端点仅作文档契约示例 curl -X POST -F filetranscript.txt http://localhost:5167/upload-transcript # 2. 查询处理状态process_id 即提交时返回的 ID curl http://localhost:5167/get-summary/1a2e5c9c-a35f-452f-9f92-be66620fcb3f基于当前源码可直接使用的 JSON 方式curl -X POST http://localhost:5167/process-transcript \ -H Content-Type: application/json \ -d { text: 会议转录全文……, model: ollama, model_name: qwen2.5:14b, meeting_id: meeting-123, chunk_size: 5000, overlap: 1000 }9.2 Python 端到端工作流脚本仓库提供了完整可运行的调用示例 backend/examples/run_summary_workflow.py核心流程为提交 → 轮询两阶段# 读取转录文件并提交处理默认每 5 秒轮询一次最多 24 次约 120 秒超时 python examples/run_summary_workflow.py transcript.txt \ --base-url http://localhost:5167 \ --provider openai \ --model-name gpt-4o-2024-11-20 \ --chunk-size 40000 \ --overlap 1000脚本关键点提交阶段调用/process-transcript发送text、model、model_name、meeting_id、chunk_size、overlap其中meeting_id由脚本用uuid4自动生成形如test-meeting-uuid响应返回的process_id用于后续轮询。轮询阶段对/get-summary/{process_id}发起 GET202 表示仍在处理status completed时取出data字段打印格式化 JSONerror/failed状态打印后端错误信息404 提示 meeting_id 不存在。超时控制--interval默认 5s与--attempts默认 24两个参数共同决定最长等待时间可在 CLI 中调整。十、注意事项与最佳实践大转录自动分块长文本会自动按chunk_size/overlap滑窗切分因此单次请求可提交远超模型上下文长度的转录内容但要注意 10MB 的文本上限backend/app/db.py。处理时长波动处理耗时随转录长度、模型响应速度变化。云端模型主要受 API 延迟影响本地 Ollama 受机器算力影响建议轮询间隔至少 5 秒并设置合理超时。时间戳格式start与end均采用 ISO 8601 格式datetime.utcnow().isoformat()。Block 颜色约定color字段仅gray与空串有意义其余值按默认色渲染前端样式层据此做 UI 着色。模型与 Key 的对应关系Claude 的 Key 存储在settings表的anthropicApiKey列供应商名为claudeGroq/OpenAI/Ollama 分别对应groqApiKey/openaiApiKey/ollamaApiKey供应商白名单与列映射见 backend/app/db.py。文档与实现的差异使用本服务前建议对照本文第五、六节以当前源码backend/app/main.py、backend/app/transcript_processor.py、backend/app/db.py为准官方文档 backend/API_DOCUMENTATION.md 中的/upload-transcript端点、DB_PATH变量名与部分数据模型键名属于早期契约与本仓库当前实现存在出入。结语Meetily 的 Python 后端以提交文本 → 异步分块处理 → 轮询取回结构化摘要的简洁模型把多供应商 LLM 接入、文本滑窗分块、SQLite 持久化与前端渲染适配收敛在三个模块之内。结合本文的端点契约、数据模型与源码级原理说明你可以直接基于 backend/examples/run_summary_workflow.py 或 curl 快速接入会议纪要生成能力并依据第六、七节的内部约定定制自己的摘要消费端。【免费下载链接】meetilyPrivacy first, AI meeting assistant with 4x faster Parakeet/Whisper live transcription, speaker diarization, and Ollama summarization built on Rust. 100% local processing. no cloud required. Meetily (Meetly Ai - https://meetily.ai) is the #1 Self-hosted, Open-source Ai meeting note taker for macOS Windows. Understand How to write meeting minutes项目地址: https://gitcode.com/GitHub_Trending/me/meetily创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Meetily 后端 API 实战指南：基于 FastAPI 的会议纪要生成服务从配置到调用
Meetily 后端 API 实战指南基于 FastAPI 的会议纪要生成服务从配置到调用【免费下载链接】meetilyPrivacy first, AI meeting assistant with 4x faster Parakeet/Whisper live transcription, speaker diarization, and Ollama summarization built on Rust. 100% local processing. no cloud required. Meetily (Meetly Ai - https://meetily.ai) is the #1 Self-hosted, Open-source Ai meeting note taker for macOS Windows. Understand How to write meeting minutes项目地址: https://gitcode.com/GitHub_Trending/me/meetily本指南系统讲解 Meetily 项目后端 Python 服务的完整 API 能力涵盖环境搭建、数据库初始化、服务启动、转录文本分块处理、结构化会议纪要生成与状态轮询等全流程。读完本文你将掌握process-transcript、get-summary等核心端点的请求与响应契约、Block/Section 数据模型的内部约定并能基于仓库自带的 Python 工作流脚本快速接入这套会议摘要 API。一、服务定位与整体架构Meetily 的 Python 后端是一个基于 FastAPI 构建的轻量级 API 服务核心职责是接收会议转录文本调用 AI 模型Claude、Groq、OpenAI 或本地 Ollama生成结构化会议纪要并将处理过程与结果持久化到本地 SQLite 数据库。它面向的典型场景是Whisper 等引擎实时产出转录文本后由前端或外部脚本提交给本服务完成智能摘要随后前端以轮询方式获取结构化摘要结果用于渲染。从源码结构看服务由三个核心模块构成模块文件职责应用入口backend/app/main.pyFastAPI 应用、路由定义、后台任务调度、CORS 配置数据处理backend/app/transcript_processor.py转录文本分块、AI Agent 调用、结构化输出校验数据持久化backend/app/db.pySQLite 表管理、进程状态跟踪、配置与 API Key 存储另有 backend/app/schema_validator.py 在启动时对数据库表结构做自动校验与缺失列补全保证旧库平滑升级。官方 API 文档位于仓库 backend/API_DOCUMENTATION.md本文以其为骨架展开并深入对应源码讲解底层实现原理。二、环境准备与安装2.1 系统要求运行本服务需要满足Python 3.8 或更高版本pipPython 包安装器SQLite 3足够的磁盘空间用于存放数据库与转录文本数据2.2 环境变量配置在backend目录下创建.env文件写入以下变量# API Keys ANTHROPIC_API_KEYyour_anthropic_api_key # Required for Claude model GROQ_API_KEYyour_groq_api_key # Optional, for Groq model # Database Configuration DB_PATH./meetings.db # SQLite database path # Server Configuration HOST0.0.0.0 # Server host PORT5167 # Server port # Processing Configuration CHUNK_SIZE5000 # Default chunk size for processing CHUNK_OVERLAP1000 # Default overlap between chunks需要说明的几点源码级细节数据库路径官方文档将环境变量写作DB_PATH但当前 backend/app/db.py 中DatabaseManager实际读取的是DATABASE_PATH未设置时默认使用meeting_minutes.db。仓库根目录还提供了 backend/temp.env 模板含ANTHROPIC_API_KEY、GROQ_API_KEY、OPENAI_API_KEY三个占位键与一键配置脚本 backend/set_env.sh脚本会从系统环境读取已有 Key 或交互式提示输入并写入.env。HOST/PORT源码默认监听0.0.0.0:5167见 backend/app/main.py 的 uvicorn 启动配置.env中的HOST/PORT需在启动命令中显式传入才会生效。CHUNK_SIZE/CHUNK_OVERLAP.env中的这两个变量在 transcript_processor.py 中并未被读取实际分块参数由 API 请求体中的chunk_size与overlap字段控制默认值 5000/1000 定义于 main.py 的TranscriptRequest模型中。2.3 安装步骤# 1. 创建并激活虚拟环境 python -m venv venv source venv/bin/activate # Windows 下使用: venv\Scripts\activate # 2. 安装依赖 pip install -r requirements.txt官方文档所列依赖包为pydantic、pydantic-ai、pandas、devtools、chromadb、python-dotenv、fastapi、uvicorn、python-multipart、aiosqlite。以当前仓库 backend/requirements.txt 为准实际锁定版本如下pydantic-ai0.2.15 pydantic2.11.5 pandas2.2.3 devtools0.12.2 python-dotenv1.1.0 fastapi0.115.9 uvicorn0.34.0 python-multipart0.0.20 aiosqlite0.21.0 ollama0.5.2与文档相比实际依赖已升级pydantic-ai到 0.2.x、新增ollama客户端包用于本地模型调用且当前版本列表已不含chromadb。python-multipart是 FastAPI 处理表单/文件上传的必需依赖ollama包支撑 Ollama 本地模型的流式调用。2.4 初始化数据库python -c from app.db import init_db; import asyncio; asyncio.run(init_db())注意这条命令来自官方文档但当前源码中的初始化入口已演化为DatabaseManager类。在 backend/app/db.py 中DatabaseManager.__init__会直接执行_legacy_init_db()建表与schema_validator.validate_schema()校验补列因此实际初始化方式是在服务启动时自动完成无需手动执行单独命令。如果你需要手动初始化可参考python -c from db import DatabaseManager; DatabaseManager()建表逻辑位于 backend/app/db.py会创建以下数据表meetings会议主表id、title、created_at、updated_at、folder_pathtranscripts逐段转录文本含audio_start_time、audio_end_time、duration三个录音相对时间戳用于音文同步播放summary_processes摘要处理进程状态表status、result、error、start_time、end_time、chunk_count、processing_time 等transcript_chunks整段转录原始文本与模型参数快照settings摘要模型配置与各供应商 API Keytranscript_settings转录引擎配置localWhisper/deepgram/elevenLabs/groq/openai2.5 启动服务器uvicorn app.main:app --host 0.0.0.0 --port 5167 --reload服务启动后API 根地址http://localhost:5167FastAPI 自动生成的交互式文档http://localhost:5167/docs源码中FastAPI(titleMeeting Summarizer API, ...)定义于 backend/app/main.py若直接运行python app/main.py参考 backend/start_python_backend.cmd 的启动方式main 入口会调用uvicorn.run(main:app, host0.0.0.0, port5167, reloadTrue)效果等价。更完整的部署方式含 Docker 与 Whisper 服务编排见 backend/README.md。三、项目结构backend/ ├── app/ │ ├── __init__.py │ ├── main.py # Main FastAPI application │ ├── db.py # Database operations │ ├── schema_validator.py # Database schema validation auto-fix │ └── transcript_processor.py # Transcript processing logic ├── examples/ │ └── run_summary_workflow.py # 端到端调用示例脚本 ├── requirements.txt # Python dependencies ├── temp.env # 环境变量模板 ├── set_env.sh # 环境变量配置脚本 └── meeting_minutes.db # SQLite database (启动后生成)四、API 概览Base URLhttp://localhost:5167认证目前所有端点均无需认证即可访问官方文档明确说明 Currently, no authentication is required for API endpoints。不过在 main.py 的后台处理逻辑中对claude/groq/openai三类云端供应商做了二次校验若数据库中未配置对应 API Key任务会被标记为失败并返回 API key not configured 的明确错误。也就是说接口层无认证但调用云端模型前必须有有效 Key。CORS为方便本地前后端联调服务通过CORSMiddleware放行了所有来源、方法与请求头预检请求缓存 1 小时见 backend/app/main.py。五、核心端点详解5.1 Process Transcript —— 直接提交转录文本Endpoint:/process-transcriptMethod:POSTContent-Type:application/json提交一段转录文本服务立即返回处理 ID 并异步执行摘要生成。请求体{ text: string, // Required: The transcript text model: string, // Required: AI model to use (e.g., ollama) model_name: string, // Required: Model version (e.g., qwen2.5:14b) chunk_size: 40000, // Optional: Size of text chunks (default: 5000) overlap: 1000 // Optional: Overlap between chunks (default: 1000) }对照源码 backend/app/main.py 中的TranscriptRequest模型实际请求体还包含两个字段meeting_id必填会议 ID用于关联会议记录。响应返回的process_id在实现中就是这个meeting_id见下文。custom_prompt可选自定义摘要提示词默认值为Generate a summary of the meeting transcript.会被注入到每个分块的 AI 提示中。chunk_size与overlap的参数校验在SummaryProcessor.process_transcript中完成backend/app/main.pychunk_size必须为正数overlap必须非负且小于chunk_size若overlap chunk_size会被自动调整为chunk_size - 1以保证步长为正。响应{ process_id: string, message: Processing started }后台处理流程backend/app/main.py先通过db.create_process(meeting_id)在summary_processes表中创建/重置状态为PENDING的进程记录再调用db.save_transcript将原始文本与模型参数快照写入transcript_chunks表最后通过 FastAPI 的BackgroundTasks将摘要任务放入后台线程执行接口立即返回不阻塞调用方。5.2 Upload Transcript —— 上传转录文件Endpoint:/upload-transcriptMethod:POSTContent-Type:multipart/form-data官方文档记载此端点提供与/process-transcript相同的功能但以文件上传替代原始文本参数如下参数类型必填说明fileFile是要上传的转录文件modelString否AI 模型默认 claudemodel_nameString否具体模型版本默认 claude-3-5-sonnet-latestchunk_sizeInteger否文本分块大小默认 5000overlapInteger否分块重叠默认 1000响应同样为{ process_id: string, message: Processing started }重要提示经过对当前仓库源码的检索backend/app/main.py 中暂未找到/upload-transcript的路由实现该路径目前仅出现在文档中。因此该端点属于文档记载的接口契约若你依赖文件上传能力请以当前实际运行的源码为准优先使用/process-transcript提交文本或自行按文档契约补充实现。5.3 Get Summary —— 获取摘要结果Endpoint:/get-summary/{process_id}Method:GET路径参数参数类型必填说明process_idString是要查询的处理 ID这里的process_id与/process-transcript传入的meeting_id等价create_process方法直接以meeting_id作为进程主键backend/app/db.py因此轮询时使用响应返回的process_id即可。响应状态码语义CodeDescription200Success - Summary completed202Accepted - Processing in progress400Bad Request - Failed or unknown status404Not Found - Process ID not found500Internal Server Error - Server-side error响应体{ status: string, // completed, processing, error meetingName: string, // Name of the meeting (null if not available) process_id: string, // Process ID data: { // Summary data (null if not completed) MeetingName: string, SectionSummary: { title: string, blocks: [ { id: string, type: string, content: string, color: string } ] }, CriticalDeadlines: { title: string, blocks: [] }, KeyItemsDecisions: { title: string, blocks: [] }, ImmediateActionItems: { title: string, blocks: [] }, NextSteps: { title: string, blocks: [] }, OtherImportantPoints: { title: string, blocks: [] }, ClosingRemarks: { title: string, blocks: [] } }, start: string, // Start time in ISO format (null if not started) end: string, // End time in ISO format (null if not completed) error: string // Error message if status is error }对照 backend/app/main.py 的get_summary实现响应细节如下实际响应字段为meeting_id而非文档示例中的process_id其余字段一致状态映射PENDING/processing/started统一归一为processing并返回 202completed返回 200失败返回 400 且data置空摘要数据会做一次前端适配转换将后端各 Section 标题转为 snake_case 键如Session Summary→session_summary同名 Section 自动追加索引后缀防覆盖并额外输出_section_order数组以保持前端渲染顺序backend/app/main.py文档示例中的SectionSummary等键名取自早期版本约定当前源码生成的摘要结构以 transcript_processor.py 中的SummaryResponse模型为准见第六节。5.4 扩展端点源码已实现文档未覆盖当前源码在文档三个端点之外还实现了一组会议管理端点均位于 backend/app/main.py可用于完整的会议记录生命周期管理端点方法功能/get-meetingsGET获取全部会议列表id、title、created_at/get-meeting/{meeting_id}GET获取会议详情及全部转录段落/save-transcriptPOST保存转录段落含音文同步时间戳不触发摘要/save-meeting-titlePOST更新会议标题/delete-meetingPOST删除会议及其全部关联数据按外键顺序级联清理/save-meeting-summaryPOST手动保存/更新会议摘要/search-transcriptsPOST基于LIKE的转录全文检索返回匹配上下文片段±100 字符/get-model-config、/save-model-configGET/POST摘要模型配置读写/get-transcript-config、/save-transcript-configGET/POST转录引擎配置读写/get-api-key、/get-transcript-api-keyPOST读取指定供应商 API Key/save-model-config附带POST保存供应商 API Key六、数据模型与结构化输出约定6.1 Block —— 内容块Block是摘要内容的最小单元其 Pydantic 定义位于 backend/app/transcript_processor.py{ id: string, // Unique identifier type: string, // Type of block (text, action, decision, etc.) content: string, // Content text color: string // Color for UI display }源码将type收紧为字面量联合类型且与前端渲染能力严格对齐text普通段落bullet列表项heading1一级标题heading2二级标题color字段当前前端只使用gray次要内容灰色与空字符串默认色任何其他值都会按默认色渲染。这些约束会通过 pydantic-ai 的提示词明确告知模型见 transcript_processor.py保证输出符合前端组件预期。6.2 Section —— 摘要分区{ title: string, // Section title blocks: [ // Array of Block objects { id: string, type: string, content: string, color: string } ] }6.3 SummaryResponse —— 分块摘要的完整结构pydantic-ai 的Agent以SummaryResponse为结构化输出目标transcript_processor.py包含字段类型说明MeetingNamestr会议名称PeoplePeople参会人格式约定Title - Person Name (Role, Details)要求始终输出该分区SessionSummarySection会议摘要CriticalDeadlinesSection关键截止日期KeyItemsDecisionsSection关键事项与决策ImmediateActionItemsSection立即执行项NextStepsSection后续步骤MeetingNotesMeetingNotes会议笔记meeting_name sections 列表分块处理完成后main.py 中的process_transcript_background会将所有分块的 JSON 结果聚合为最终摘要会议名称取首个非空值各 Section 的 blocks 跨分块合并去重按 title 匹配后追加MeetingNotes.sections同步聚合并自动为每个分区补齐blocks数组避免前端渲染空指针。七、分块处理与模型适配原理7.1 分块策略TranscriptProcessor.process_transcriptbackend/app/transcript_processor.py按滑窗方式切分文本step chunk_size - overlap chunks [text[i:ichunk_size] for i in range(0, len(text), step)]即相邻分块间保留overlap长度的重复文本防止关键信息恰好被切分边界截断。每个分块独立交给 AI 模型生成一份SummaryResponse若某分块无相关分区内容如关键截止日期提示词要求模型返回空 blocks 列表而非省略字段transcript_processor.py。处理失败的分块会被跳过并记录日志不影响其余分块的结果汇总。7.2 模型供应商适配model参数支持四种供应商初始化逻辑见 transcript_processor.pymodel 值底层实现备注claudeAnthropicModelAnthropicProviderKey 存于 settings 表 anthropicApiKeygroqGroqModelGroqProviderKey 存于 settings 表 groqApiKeyopenaiOpenAIModelOpenAIProviderKey 存于 settings 表 openaiApiKeyollamaOpenAIModel指向本地兼容端点或AsyncClient流式调用见下文Ollama 本地模型的特殊逻辑OpenAI 兼容路径通过环境变量OLLAMA_HOST默认http://localhost:11434构造{host}/v1作为 OpenAI 兼容 base URLtranscript_processor.py因此 Ollama 服务需开启 OpenAI 兼容 API。分块大小自动适配当model_name以phi4或llama开头时chunk_size强制设为 10000其他模型设为 30000overlap固定 1000transcript_processor.py。这是针对本地模型上下文窗口的保守适配意味着调用方传入的chunk_size对 Ollama 会被覆盖。流式输出与 JSON Schema 约束chat_ollama_modeltranscript_processor.py使用AsyncClient.chat(..., streamTrue, formatSummaryResponse.model_json_schema())流式读取并通过model_json_schema()将结构化输出约束下发给 Ollama收到的响应再用SummaryResponse.model_validate_json校验若解析失败则返回原始字符串交由上层降级处理。云端模型claude/groq/openai则统一走agent.run(...)pydantic-ai 负责基于SummaryResponse自动生成 JSON Schema 并做重试result_retries2。7.3 多转录并发处理官方文档 Notes 中提到 The API supports concurrent processing of multiple transcripts。从实现看每次请求都会生成独立的后台任务SQLite 写入通过事务与BEGIN TRANSACTION保证一致性summary_processes表以meeting_id为键支持并发插入更新。需要留意 SQLite 的写锁特性高并发场景下建议评估写入频率。八、状态码与错误处理8.1 通用状态码CodeDescription200Success - Request completed successfully202Accepted - Processing in progress400Bad Request - Invalid request or parameters404Not Found - Process ID not found500Internal Server Error - Server-side error8.2 错误响应格式所有错误响应统一遵循以下结构{ status: error, meetingName: null, process_id: string, data: null, start: null, end: null, error: Error message describing what went wrong }实现细节backend/app/db.py错误信息写入数据库前会做换行/回车剥离并截断到 1000 字符防止日志注入任务最终状态为COMPLETED或FAILED时自动记录end_time。常见的可预期失败场景云端供应商未配置 API Key → 任务状态置为failedget-summary返回 400转录文本为空 → 后台任务直接抛出ValueError转录文本超过 10MB →save_transcript拒绝写入backend/app/db.py查询不存在的 meeting_id → 返回 404。九、完整调用示例9.1 curl 快速验证# 1. 上传并处理转录文件注意见 5.2 节提示当前源码未实现该端点仅作文档契约示例 curl -X POST -F filetranscript.txt http://localhost:5167/upload-transcript # 2. 查询处理状态process_id 即提交时返回的 ID curl http://localhost:5167/get-summary/1a2e5c9c-a35f-452f-9f92-be66620fcb3f基于当前源码可直接使用的 JSON 方式curl -X POST http://localhost:5167/process-transcript \ -H Content-Type: application/json \ -d { text: 会议转录全文……, model: ollama, model_name: qwen2.5:14b, meeting_id: meeting-123, chunk_size: 5000, overlap: 1000 }9.2 Python 端到端工作流脚本仓库提供了完整可运行的调用示例 backend/examples/run_summary_workflow.py核心流程为提交 → 轮询两阶段# 读取转录文件并提交处理默认每 5 秒轮询一次最多 24 次约 120 秒超时 python examples/run_summary_workflow.py transcript.txt \ --base-url http://localhost:5167 \ --provider openai \ --model-name gpt-4o-2024-11-20 \ --chunk-size 40000 \ --overlap 1000脚本关键点提交阶段调用/process-transcript发送text、model、model_name、meeting_id、chunk_size、overlap其中meeting_id由脚本用uuid4自动生成形如test-meeting-uuid响应返回的process_id用于后续轮询。轮询阶段对/get-summary/{process_id}发起 GET202 表示仍在处理status completed时取出data字段打印格式化 JSONerror/failed状态打印后端错误信息404 提示 meeting_id 不存在。超时控制--interval默认 5s与--attempts默认 24两个参数共同决定最长等待时间可在 CLI 中调整。十、注意事项与最佳实践大转录自动分块长文本会自动按chunk_size/overlap滑窗切分因此单次请求可提交远超模型上下文长度的转录内容但要注意 10MB 的文本上限backend/app/db.py。处理时长波动处理耗时随转录长度、模型响应速度变化。云端模型主要受 API 延迟影响本地 Ollama 受机器算力影响建议轮询间隔至少 5 秒并设置合理超时。时间戳格式start与end均采用 ISO 8601 格式datetime.utcnow().isoformat()。Block 颜色约定color字段仅gray与空串有意义其余值按默认色渲染前端样式层据此做 UI 着色。模型与 Key 的对应关系Claude 的 Key 存储在settings表的anthropicApiKey列供应商名为claudeGroq/OpenAI/Ollama 分别对应groqApiKey/openaiApiKey/ollamaApiKey供应商白名单与列映射见 backend/app/db.py。文档与实现的差异使用本服务前建议对照本文第五、六节以当前源码backend/app/main.py、backend/app/transcript_processor.py、backend/app/db.py为准官方文档 backend/API_DOCUMENTATION.md 中的/upload-transcript端点、DB_PATH变量名与部分数据模型键名属于早期契约与本仓库当前实现存在出入。结语Meetily 的 Python 后端以提交文本 → 异步分块处理 → 轮询取回结构化摘要的简洁模型把多供应商 LLM 接入、文本滑窗分块、SQLite 持久化与前端渲染适配收敛在三个模块之内。结合本文的端点契约、数据模型与源码级原理说明你可以直接基于 backend/examples/run_summary_workflow.py 或 curl 快速接入会议纪要生成能力并依据第六、七节的内部约定定制自己的摘要消费端。【免费下载链接】meetilyPrivacy first, AI meeting assistant with 4x faster Parakeet/Whisper live transcription, speaker diarization, and Ollama summarization built on Rust. 100% local processing. no cloud required. Meetily (Meetly Ai - https://meetily.ai) is the #1 Self-hosted, Open-source Ai meeting note taker for macOS Windows. Understand How to write meeting minutes项目地址: https://gitcode.com/GitHub_Trending/me/meetily创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
