5分钟上手！开源notesGPT语音笔记全攻略：从安装到智能转录
项目地址: https://gitcode.com/gh_mirrors/no/notesGPT 你还在为会议记录手忙脚乱？重要灵感转头就忘？作为开发者/学生/职场人，每天80%的信息碎片都在无意识中流失。notesGPT——这款基于Convex+Whisper+LLM的开源语音笔记神器，能让你用声音捕捉灵感，自动转录成文字并生成待办事项。本文将带你从0到1搭建属于自己的AI语音笔记系统，包含环境配置、核心功能拆解和高级玩法，全程实操无废话。
读完本文你将获得：
- 3步完成本地部署（附排坑指南）
- 掌握语音转录→摘要生成→任务提取全流程
- 自定义LLM模型参数优化输出质量
- 接入Notion等第三方工具的扩展方案
技术架构全景图
notesGPT采用现代化全栈架构，核心组件如下：
| 技术组件 | 核心作用 | 优势 |
|---|---|---|
| Convex | 实时数据库+云函数 | 毫秒级响应，自动扩缩容 |
| Next.js App Router | 前端框架 | 服务端渲染提升首屏速度 |
| Together.ai | LLM推理服务 | 低成本接入Mixtral等开源大模型 |
| Whisper | 语音转文字 | 支持99种语言，离线可用 |
| Clerk | 用户认证 | 5分钟集成OAuth/邮箱登录 |
环境准备与部署
系统要求
- Node.js 18.x+
- npm 9.x+
- Git
- 现代浏览器（Chrome 100+/Edge 100+）
部署步骤
1. 获取源码
git clone https://gitcode.com/gh_mirrors/no/notesGPT.git
cd notesGPT
2. 安装依赖
# 安装项目依赖
npm install
# 启动开发环境（会自动启动Convex后端和Next.js前端）
npm run dev
3. 配置关键服务
⚠️ 首次启动会提示缺少环境变量，需要完成以下配置
Clerk认证配置：
- 访问 Clerk官网 注册账号
- 创建应用，获取
CLERK_SECRET_KEY和NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY - 在项目根目录创建
.env.local文件：
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx
CLERK_SECRET_KEY=sk_test_xxx
CLERK_ISSUER_URL=https://your-domain.clerk.accounts.dev
Together.ai API配置：
- 访问 Together.ai 获取API密钥
- 在Convex控制台添加环境变量：
TOGETHER_API_KEY=your_together_api_key
4. 验证部署
访问 http://localhost:3000，看到登录界面即表示部署成功。首次登录可使用第三方账号或邮箱注册。
核心功能使用指南
1. 录制语音笔记
操作步骤：
- 在首页点击紫色麦克风图标（录制中会变为红色脉冲状态）
- 口述内容（支持英语及多语言混合输入）
- 完成后点击停止按钮，系统自动开始转录
💡 最佳实践：单次录音控制在5分钟内，背景噪音会影响转录 accuracy
2. 查看与管理转录内容
转录完成后自动跳转至笔记详情页，界面分为左右两栏：
- 左侧：原始转录文本（可切换为AI生成摘要）
- 右侧：智能提取的行动项列表
关键操作：
- 点击转录文本区域顶部的切换按钮可在原文和摘要间切换
- 勾选行动项前的复选框可标记完成（会触发删除动画）
- 点击"View All Action Items"查看历史待办事项
3. 高级搜索功能
系统会自动为每条笔记生成向量嵌入，支持语义搜索：
- 在仪表盘顶部搜索框输入关键词（如"项目截止日期"）
- 系统返回相关度最高的笔记，即使未包含精确关键词
代码级深度定制
自定义转录语言
默认配置为英语，修改Convex函数支持多语言：
// convex/whisper.ts
export const chat = internalAction({
args: { fileUrl: v.string(), id: v.id('notes') },
handler: async (ctx, args) => {
const res = await togetherAiClient.audio.transcriptions.create({
file: args.fileUrl,
model: 'openai/whisper-large-v3',
language: 'zh', // 修改为目标语言代码，如'zh'中文/'ja'日语
});
// ...后续处理
},
});
调整LLM摘要长度
修改提示词模板控制输出长度：
// convex/together.ts (需创建)
const SUMMARY_PROMPT = `
Summarize the following transcript in 3 sentences maximum:
{transcription}
`;
常见问题解决
部署时Convex连接失败
# 检查Convex是否正确初始化
npx convex dev --until-success
# 确保.env.local中的CLERK_ISSUER_URL正确
echo $CLERK_ISSUER_URL
转录速度慢
- 问题原因：Together.ai API调用超时
- 解决方案：切换至本地Whisper模型
# 安装本地Whisper依赖
pip install openai-whisper
未来功能展望
根据项目 roadmap，即将支持的实用功能：
- Notion双向同步：行动项自动同步至Notion数据库
- 离线工作模式：本地完成语音转录，保护隐私
- 多语言摘要：自动翻译成10种主流语言
- 自定义提示模板：根据行业需求定制摘要格式
总结与资源
notesGPT通过"语音输入→AI处理→行动输出"的极简流程，重新定义了笔记工具。其开源架构允许开发者根据需求深度定制，无论是个人知识管理还是团队协作场景都能胜任。
📚 扩展资源：
- 官方文档：项目根目录
docs/文件夹 - 问题反馈：提交issue至GitCode仓库
- 社区讨论：加入项目Discussions板块
✨ 行动倡议：
- 收藏本文以备部署时参考
- 关注项目仓库获取更新通知
- 尝试贡献代码，特别是"未来任务"列表中的功能
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
