简介Cluelessly 是一套面向开发者与团队协作场景的 AI 会议纪要助手源码聚焦实时转录、对话分析与可执行洞察生成适合希望自建会议记录工具、研究 AI 语音应用或进行二次开发的中高级开发者。项目采用 Laravel 12 与 PHP 8.2 构建后端前端基于 Vue 3.5 与 TypeScript、Inertia.js桌面端借助 NativePHP/Electron 实现本地集成AI 能力由 OpenAI Realtime API 驱动配合 Tailwind CSS 4.1 与 Vite 6 完成样式与构建SQLite 负责本地会话存储。压缩包共 347 个文件约 65.05MB以 155 个 vue 组件、77 个 php 后端逻辑、41 个 ts 脚本为主另含 md 文档、sh 脚本、json 配置及少量图片与音频采集相关文件结构完整。已有 115 人学习关注。读者可获得涵盖实时转录、动作项提取、上下文保护与见解生成的完整工程实现便于快速部署验证与功能扩展。1. 从两小时录音到一页纸Cluelessly 到底替谁省了事上周三晚上十点某公司做后端的老张给我发来一段 1 小时 47 分的会议录音说“你帮我看看这个 AI 会议纪要助手到底靠不靠谱我明天晨会要用”。我打开这份 Cluelessly 的源码包从音频解码一路翻到纪要生成跑完一遍发现它真正解决的问题不是“转文字”而是把转写、说话人切分、要点抽取、待办归并串成了一条能落地的流水线。市面上多数 AI 会议记录工具要么只给逐字稿要么把摘要做得像散文Cluelessly 的定位更接近“会议后处理中间件”输入音频或实时流输出结构化的议题、决议、行动项。它适合三类人——需要批量处理会议录音的团队工具开发者、想二次开发会议机器人的全栈工程师、以及被逐字稿淹没又不想手动整理的产品经理。源码是完整的前后端加推理服务都在不是那种只给个 demo 页面的半成品。2. 拆开 Cluelessly 的流水线音频进、结构化纪要出2.1 四个核心模块与数据流转Cluelessly 的架构不复杂但每个环节都有取舍。整条链路是音频预处理 → 语音转写ASR→ 说话人分离Diarization→ 纪要生成LLM 摘要 结构化抽取。源码目录里audio_pipeline/负责重采样和静音切分asr_engine/封装了转写模型调用diarization/做说话人聚类summarizer/是纪要生成的核心。数据流不是串行阻塞的转写和说话人分离可以并行跑最后按时间戳对齐合并。这个设计的好处是如果转写模型换了说话人模块不用动如果只想出逐字稿把 summarizer 关掉就行。我一般会先看config/pipeline.yaml里面定义了各阶段的开关和模型路径。默认配置下音频先被切成 30 秒片段做 VAD语音活动检测静音段直接跳过这一步能省掉 20% 到 40% 的推理时间。转写输出带词级时间戳说话人分离输出的是“谁在什么时间段说话”两者按时间窗口做交集对齐。对齐逻辑在utils/align.py里用的是重叠区间匹配不是简单的最近邻这点比很多开源实现讲究。2.2 环境搭建与依赖安装源码包解压后先看requirements.txt和README里的环境说明。Python 版本要求 3.9 以上推荐 3.10。核心依赖包括音频处理库、推理运行时和 Web 框架。我习惯用虚拟环境隔离避免和系统里的包打架。# 创建虚拟环境并激活 python3.10 -m venv venv_cluelessly source venv_cluelessly/bin/activate # 安装核心依赖国内网络建议加镜像源 pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple # 如果要用 GPU 推理额外装对应版本的运行时 pip install torch2.1.0cu118 -f https://download.pytorch.org/whl/torch_stable.html这里有个参数要注意requirements.txt里对推理运行时的版本卡得比较死不要随意升级。我试过把 torch 升到 2.2结果 diarization 模块的某个算子不兼容报了一堆看不懂的错。如果只是跑 CPU 推理把 GPU 相关的包注释掉就行速度慢但功能完整。安装完成后跑python -m pytest tests/做自检通过的用例数应该在 40 个以上少于这个数说明依赖没装全。2.3 配置文件的关键参数怎么调config/pipeline.yaml是整条流水线的控制中心改错一个参数可能让纪要质量断崖式下跌。下面这张表是我实际调过的几个关键项参数名默认值作用调整建议asr.chunk_size30音频切片长度秒网络差或音频质量低时降到 15asr.languageauto转写语言中英混会时强制设 zh否则英文词会被吞diarization.min_speakers2最少说话人数单人录音设为 1否则会强行切出两个人diarization.cluster_threshold0.7聚类阈值调高到 0.8 说话人更少调低到 0.6 更细summarizer.max_tokens2048纪要生成长度上限长会议调到 4096但注意模型上下文限制summarizer.temperature0.3生成随机性要稳定输出别超过 0.5要发散可到 0.7改完配置后不用重启服务Cluelessly 支持热加载但只对下一个任务生效。正在跑的任务还是用旧配置。这个设计在批量处理时很有用可以边跑边调。2.4 跑通第一个会议纪要任务环境好了、配置调了接下来用一段测试音频跑通全流程。源码包的samples/目录下有一段 3 分钟的模拟会议录音两个人对话带一点背景噪声。命令行入口是main.py支持文件和实时流两种模式。# 用示例音频跑一次完整流水线 python main.py \ --input samples/meeting_demo.wav \ --output outputs/demo_result.json \ --config config/pipeline.yaml \ --enable-diarization \ --enable-summary # 查看输出结构 cat outputs/demo_result.json | python -m json.tool | head -50输出是一个 JSON包含transcript逐字稿、speakers说话人时间段、summary纪要正文、action_items行动项列表。action_items是单独抽出来的每条带负责人和截止时间如果原文提到了。我跑下来发现3 分钟音频在 CPU 上大约 40 秒出结果GPU 上 8 秒左右。如果输出里action_items为空先检查summarizer的 prompt 模板是不是被改过默认模板在prompts/summary_zh.txt里对中文会议做了优化。3. 把 Cluelessly 接进自己的系统API 封装与批量处理3.1 启动 HTTP 服务并调用接口命令行适合调试真正要用还是得走 API。Cluelessly 自带一个基于 FastAPI 的服务端启动命令在server/目录下。默认监听 8000 端口支持上传音频文件和提交转写任务两种模式。# 启动 API 服务 cd server uvicorn app:app --host 0.0.0.0 --port 8000 --workers 2 # 另开终端提交一个音频文件 curl -X POST http://localhost:8000/api/v1/transcribe \ -H Content-Type: multipart/form-data \ -F filesamples/meeting_demo.wav \ -F enable_summarytrue \ -F languagezh接口返回一个task_id后续用/api/v1/task/{task_id}查状态和结果。--workers参数控制并发进程数CPU 推理建议设为核数的一半GPU 推理设为 1 到 2 就行多了会抢显存。我试过 4 个 worker 同时跑 GPU 推理结果第三个任务开始就 OOM 了血泪经验是 GPU 场景下 worker 数别超过 GPU 数量。3.2 批量处理会议录音的脚本写法实际场景里往往是一堆录音要处理一个个调 API 太慢。我写了个批量脚本核心是控制并发数和失败重试。Cluelessly 的任务队列是内存级的重启就丢所以批量处理时要把结果落盘。import requests import os import time from concurrent.futures import ThreadPoolExecutor, as_completed API_BASE http://localhost:8000/api/v1 AUDIO_DIR recordings/ OUTPUT_DIR results/ MAX_WORKERS 2 # GPU 场景别超过 2 def process_one(audio_file): 提交单个音频并轮询结果 filepath os.path.join(AUDIO_DIR, audio_file) with open(filepath, rb) as f: resp requests.post( f{API_BASE}/transcribe, files{file: f}, data{enable_summary: true, language: zh}, timeout30 ) task_id resp.json()[task_id] # 轮询直到完成最多等 10 分钟 for _ in range(120): time.sleep(5) status requests.get(f{API_BASE}/task/{task_id}).json() if status[state] done: return audio_file, status[result] elif status[state] failed: return audio_file, {error: status.get(message, unknown)} return audio_file, {error: timeout} # 批量提交控制并发 audio_files [f for f in os.listdir(AUDIO_DIR) if f.endswith((.wav, .mp3))] with ThreadPoolExecutor(max_workersMAX_WORKERS) as executor: futures {executor.submit(process_one, f): f for f in audio_files} for future in as_completed(futures): name, result future.result() out_path os.path.join(OUTPUT_DIR, name .json) with open(out_path, w, encodingutf-8) as f: json.dump(result, f, ensure_asciiFalse, indent2) print(fdone: {name})这段脚本的关键点是MAX_WORKERS和轮询间隔。MAX_WORKERS设大了会把服务打挂设小了处理慢。我的经验是 CPU 推理设 4GPU 推理设 2。轮询间隔 5 秒是折中值太短浪费请求太长结果延迟。另外注意timeout30是上传超时大文件要调大不然传一半就断了。3.3 输出格式定制与下游对接Cluelessly 默认输出 JSON但很多团队需要 Markdown 或直接推到协作工具。源码里exporters/目录提供了几个导出器包括 Markdown、纯文本和一种简化的表格格式。如果都不满足可以自己写一个只要实现export(result) - str接口就行。# 自定义导出器示例输出带行动项的 Markdown from exporters.base import BaseExporter class MyMarkdownExporter(BaseExporter): def export(self, result): lines [# 会议纪要\n] lines.append(f## 摘要\n{result[summary]}\n) lines.append(## 行动项\n) for item in result.get(action_items, []): owner item.get(owner, 待定) deadline item.get(deadline, 未定) lines.append(f- [ ] {item[content]} 负责人{owner}截止{deadline}) return \n.join(lines)把这个文件放到exporters/下然后在配置里把export.format改成my_markdown就能生效。注意行动项里的owner和deadline是 LLM 从原文抽的不一定准下游用之前最好人工过一眼。我一般会在导出后加一个校验步骤把没有负责人的行动项标红。4. 避坑与排查那些让我加班到凌晨的坑4.1 转写结果全是乱码或空文本现象提交音频后返回的transcript字段是空字符串或者出现大量重复字符。原因最常见的是音频采样率不匹配。Cluelessly 的 ASR 模块期望 16kHz 单声道如果输入是 44.1kHz 立体声重采样环节可能静默失败。另一个原因是音频编码格式不被支持比如某些 AMR 或 OPUS 变体。解决先用ffprobe检查音频参数不对就先转码。命令是ffmpeg -i input.mp3 -ar 16000 -ac 1 output.wav。如果转码后还是空检查asr.chunk_size是不是设得太小小于 5 秒的片段可能被 VAD 直接过滤掉。4.2 说话人分离把一个人切成好几个现象speakers字段里出现 5 个以上说话人但实际会议只有 3 个人。原因cluster_threshold设得太低聚类过细。背景噪声、咳嗽、笑声都可能被当成独立说话人。解决把diarization.cluster_threshold从默认 0.7 调到 0.8 或 0.85同时把min_speakers设成实际人数。如果还是不行检查音频里有没有明显的信道差异比如不同麦克风录的这种情况需要先做音量归一化。4.3 纪要生成跑到一半卡住不动现象任务状态一直是running日志里最后一行停在summarizer: generating...。原因LLM 推理超时或显存不足。长会议超过 1 小时的转写文本可能超过模型上下文窗口导致生成过程被截断或挂起。解决先看summarizer.max_tokens是不是设得太大超过模型上限会直接失败。然后把长文本做分段摘要Cluelessly 支持summarizer.chunkedtrue会自动把转写切成多段分别摘要再合并。如果显存不够把summarizer.device改成cpu慢但能跑完。4.4 API 并发一高就返回 500现象批量提交时前几个任务正常后面全部返回 500 错误。原因服务端的任务队列是内存级的没有持久化并发超过 worker 数时新任务直接拒绝。另外 GPU 推理时多个 worker 抢显存会导致 OOM。解决把--workers降到 1 到 2然后在客户端做限流用队列控制提交速度。如果任务量大建议在 Cluelessly 前面加一层消息队列比如用 Redis 做任务缓冲客户端只负责投递不直接调 API。4.5 中文会议里英文术语被转写错现象转写结果里“API”变成“A批”“Kubernetes”变成“库伯耐提斯”。原因ASR 模型的语言设置是auto在中英混说时倾向于用中文音译英文词。解决把asr.language强制设为zh同时在asr.hotwords里加入常用英文术语列表。Cluelessly 支持热词增强格式是每行一个词。我一般会把团队常用的技术栈词汇都加进去转写准确率能提升不少。5. 进阶用热词和后处理把纪要质量再拉一档跑通基础流程后真正拉开差距的是细节调优。Cluelessly 的asr.hotwords支持动态加载我习惯在每次会议前根据议程生成一个热词文件。比如这次会议要讨论“推荐系统召回率”就把“召回率”“协同过滤”“Embedding”加进去。热词文件放在config/hotwords/下按会议类型分文件配置里引用对应文件就行。另一个提质量的手段是后处理。Cluelessly 输出的action_items有时候会把“我们下周看看”这种模糊表述也抽进来我加了一个过滤规则只保留包含明确动词完成、提交、确认、上线和明确时间本周、下周一、月底的条目。规则写在postprocess/filter.py里用正则匹配简单但有效。验证纪要质量我一般用两个指标行动项召回率和摘要压缩比。召回率靠人工标注几段会议做基准压缩比是摘要字数除以转写字数中文会议一般在 5% 到 10% 之间比较合理。低于 5% 说明摘要太简略高于 15% 说明没抓住重点。我每次调完参数都会跑一遍基准集对比这两个指标的变化。从那以后我每次部署 Cluelessly 之前都会先用一段带背景噪声的双人对话做冒烟测试确认转写、分离、摘要三个环节都正常再上批量任务。这个习惯帮我省掉了至少三次半夜爬起来排查的麻烦。希望帮到你。本文还有配套的精品资源点击获取
 到 Broker 走了多远)
