这个标题其实是一段非常典型的“需求输入”“小可怎么还不洗澡”翻译成技术需求就是一条定时语音提醒任务“马上就看完这本书了我想先看完”翻译成技术需求就是阅读进度跟踪与延迟执行逻辑。把这两句话放到一起看它就是一个很接地气的本地智能语音助手场景到点提醒、状态记录、延后处理。这篇文章要讨论的不是什么大模型推理框架而是一套可以直接落地运行的本地语音提醒助手完整方案。我会从需求拆解开始给出环境准备、接口设计、批量任务、性能观察和排错清单带你把这个“一句话需求”变成一个能用的服务。项目原理不复杂普通电脑就能跑重点在于把调度、存储、语音播报和 Web 管理端串起来。1. 核心能力速览先看这套方案要实现的整体能力。以下表格里的参数属于通用推荐值实际运行效果需要结合本机环境验证。能力项说明项目类型本地智能语音提醒助手服务核心功能定时提醒语音播报、阅读进度记录、延后提醒、Web 管理端硬件门槛普通 PC 即可无需独立显卡若接入本地 ASR/TTS 模型则需按模型评估运行平台Windows / Linux / macOS主要技术栈Python、FastAPI、APScheduler、SQLite、pyttsx3启动方式命令行启动 Web 服务浏览器访问管理页面接口能力提供 REST API支持创建提醒、查询任务、更新进度、批量导入书单批量任务支持书单批量导入、批量创建定时提醒实时语音播报依赖系统自带 TTS 引擎离线可用适合场景家庭个人提醒、阅读管理、学习计划、轻量自动化任务这套方案最大的优势是不依赖昂贵的云服务提醒任务、阅读进度、历史记录都存在本地数据库里。你只需要一个 Python 环境就能把服务跑起来并通过浏览器或 API 方式管理所有任务。2. 适用场景与使用边界先明确它适合谁。最典型的用户是个人和家庭场景你想让电脑在晚上 10 点提醒孩子洗澡但你正在看书希望把提醒延后 20 分钟同时记录当前阅读进度这么一套交互流程正好可以被这套服务覆盖。它适合解决的问题包括三类定时提醒类比如“小可怎么还不洗澡”“该站起来活动了”“药快吃完了”。阅读进度类记录每本书读到了多少页、剩余多少页、当前状态是“在读”还是“已完成”。延后处理类收到提醒后选择“再等 10 分钟”“我正在看书再放一会儿”系统自动重新排队提醒。不适合的场景也要说清楚。它不适合用来做无授权的公共环境录音、不适合在未告知家人的情况下采集语音数据也不需要接入任何云语音识别能力的时候优先保证隐私不出本机。如果后续扩展语音识别和语音克隆功能必须取得目标对象授权尤其是儿童和家庭成员的声音素材不能随意录入和传播。在合规层面使用 TTS 播报内容时要确保提醒文本不包含冒犯性、歧视性内容批量导入书单时也要注意书籍内容的版权边界只保留个人阅读元数据不存储整本受版权保护的电子书内容。3. 环境准备与前置条件这套服务对硬件要求极低重点在软件环境。我的建议是先跑最小闭环再逐步加语音识别模型。3.1 操作系统与运行时Windows 10/11、Ubuntu 20.04 及以上、macOS 12 及以上都可以。需要 Python 3.10 或更高版本安装完 Python 后确认 pip 可用python --version pip --version如果系统同时装了多个 Python 版本建议用python3和pip3命令做区分。3.2 需要安装的依赖核心依赖包括 FastAPI、Uvicorn、APScheduler、SQLAlchemy、pyttsx3。如果你要用浏览器调试 REST APIFastAPI 自带的 Swagger 文档页可以直接用不需要额外安装。fastapi uvicorn apscheduler sqlalchemy pyttsx3Linux 系统使用 pyttsx3 之前需要安装语音合成引擎。Ubuntu/Debian 系可以运行下面的命令Windows 和 macOS 一般直接可用sudo apt update sudo apt install espeak-ng libespeak-ng13.3 项目目录结构建议把项目统一放在一个目录下后续模型文件、日志、数据库分离管理。xiaoke_assistant/ ├── app.py ├── requirements.txt ├── database/ │ └── assistant.db ├── logs/ │ └── app.log └── static/ └── index.htmlassistant.db是 SQLite 数据库文件首次启动后自动生成logs/app.log记录服务运行日志和定时任务执行情况。3.4 端口检查服务默认监听8000端口。启动前检查端口是否被占用# Windows netstat -ano | findstr :8000 # Linux / macOS lsof -i :8000如果端口被占用可以在启动命令里指定新的端口后续所有访问地址同步修改。4. 安装部署与启动方式部署过程不复杂核心就是把依赖装好、把服务启动起来。下面先给出一份可用的主程序示例再说明启动步骤。4.1 创建虚拟环境并安装依赖在项目根目录执行cd xiaoke_assistant python -m venv venv # Windows venv\Scripts\activate # Linux / macOS source venv/bin/activate pip install -r requirements.txt4.2 主程序实现app.py里实现三个层面的功能定时调度器、数据库模型、REST API。下面是一个可直接用的最小版本覆盖提醒创建、提醒列表、阅读进度更新和语音播报触发。import sqlite3 import threading from datetime import datetime, timedelta from apscheduler.schedulers.background import BackgroundScheduler from fastapi import FastAPI, HTTPException from pydantic import BaseModel app FastAPI(title小可语音提醒助手, version0.1.0) scheduler BackgroundScheduler(timezoneAsia/Shanghai) scheduler.start() DB_PATH database/assistant.db def init_db(): conn sqlite3.connect(DB_PATH) cursor conn.cursor() cursor.execute( CREATE TABLE IF NOT EXISTS reminders ( id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL, remind_time TEXT NOT NULL, status TEXT DEFAULT pending, created_at TEXT DEFAULT CURRENT_TIMESTAMP ) ) cursor.execute( CREATE TABLE IF NOT EXISTS reading_progress ( id INTEGER PRIMARY KEY AUTOINCREMENT, book_name TEXT NOT NULL, current_page INTEGER DEFAULT 0, total_page INTEGER DEFAULT 0, status TEXT DEFAULT reading, updated_at TEXT DEFAULT CURRENT_TIMESTAMP ) ) conn.commit() conn.close() class ReminderCreate(BaseModel): title: str remind_time: str delay_minutes: int 0 class ReadingProgressUpdate(BaseModel): book_name: str current_page: int total_page: int def speak_text(text: str): try: import pyttsx3 engine pyttsx3.init() engine.say(text) engine.runAndWait() except Exception as exc: print(f[TTS 错误] {exc}) def trigger_reminder(reminder_id: int, title: str): print(f[执行提醒] {datetime.now()} - {title}) speak_text(f小可提醒你{title}) conn sqlite3.connect(DB_PATH) cursor conn.cursor() cursor.execute( UPDATE reminders SET status done WHERE id ?, (reminder_id,) ) conn.commit() conn.close() app.on_event(startup) def startup_event(): init_db() app.post(/api/reminders) def create_reminder(item: ReminderCreate): remind_time item.remind_time if item.delay_minutes 0: delay datetime.fromisoformat(remind_time) timedelta(minutesitem.delay_minutes) remind_time delay.isoformat() conn sqlite3.connect(DB_PATH) cursor conn.cursor() cursor.execute( INSERT INTO reminders (title, remind_time) VALUES (?, ?), (item.title, remind_time), ) conn.commit() reminder_id cursor.lastrowid conn.close() run_date datetime.fromisoformat(remind_time) scheduler.add_job( trigger_reminder, triggerdate, run_daterun_date, args[reminder_id, item.title], idfreminder_{reminder_id}, replace_existingTrue, ) return {id: reminder_id, title: item.title, remind_time: remind_time} app.get(/api/reminders) def list_reminders(): conn sqlite3.connect(DB_PATH) cursor conn.cursor() cursor.execute(SELECT id, title, remind_time, status FROM reminders ORDER BY remind_time DESC) rows cursor.fetchall() conn.close() return [ {id: row[0], title: row[1], remind_time: row[2], status: row[3]} for row in rows ] app.post(/api/reading/update) def update_reading_progress(item: ReadingProgressUpdate): conn sqlite3.connect(DB_PATH) cursor conn.cursor() cursor.execute( INSERT INTO reading_progress (book_name, current_page, total_page, status) VALUES (?, ?, ?, ?) , (item.book_name, item.current_page, item.total_page, reading), ) conn.commit() conn.close() return {message: 阅读进度已更新, book_name: item.book_name}启动服务uvicorn app:app --host 0.0.0.0 --port 8000启动后终端输出Uvicorn running on http://0.0.0.0:8000浏览器打开http://127.0.0.1:8000/docs就能看到 Swagger 接口文档页这是一个很好的功能自测入口。如果希望局域网内其他设备也能访问把host参数改为0.0.0.0即可但要注意服务不设鉴权时不要暴露在公网。4.3 验证服务是否正常在另一个终端执行curl http://127.0.0.1:8000/docs返回 HTML 内容说明服务正常。看到 404 则说明路由冲突检查是否在错误的目录启动了 uvicorn。5. 功能测试与效果验证服务启动后按照下面的顺序做一轮功能验证。每一类测试都包含预期结果和判断标准。5.1 创建定时提醒测试目标是确认提醒任务能写入数据库并且能被 APScheduler 调度。curl -X POST http://127.0.0.1:8000/api/reminders \ -H Content-Type: application/json \ -d {title: 小可该洗澡了, remind_time: 2025-02-01T22:00:00}预期返回{ id: 1, title: 小可该洗澡了, remind_time: 2025-02-01T22:00:00 }这时把系统时间手动调整到接近提醒时间或者把remind_time设置为当前时间之后 1 分钟观察终端是否打印[执行提醒]同时系统扬声器是否有语音播报。判断成功的标准数据库 reminders 表出现新记录。到达提醒时间后状态从pending更新为done。终端有提醒日志输出。TTS 引擎播报“小可提醒你小可该洗澡了”。常见失败点有两个一是datetime.fromisoformat无法解析带时区的字符串二是 APScheduler 默认时区和系统时区不一致导致任务提前或延后触发。建议代码里统一使用timezoneAsia/Shanghai。5.2 延后提醒测试延后提醒对应标题里的“马上就看完这本书了我想先看完”。其逻辑是收到提醒后把执行时间往后推一段时间。curl -X POST http://127.0.0.1:8000/api/reminders \ -H Content-Type: application/json \ -d {title: 小可该洗澡了延后20分钟, remind_time: 2025-02-01T22:00:00, delay_minutes: 20}预期remind_time返回2025-02-01T22:20:00DB 里存储的是延后后的时间。你可以通过查看响应内容判断延后逻辑是否生效。如果延后提醒需要支持“只延后一次”还是“每次都延后”需要再加一个delay_count字段和判断逻辑这里先跑通单次延后。5.3 阅读进度更新测试阅读进度管理是另一个核心功能。每次看书暂停后调一次接口记录当前页码。curl -X POST http://127.0.0.1:8000/api/reading/update \ -H Content-Type: application/json \ -d {book_name: 三体, current_page: 128, total_page: 302}预期返回{ message: 阅读进度已更新, book_name: 三体 }验证方法打开 SQLite 数据库查看 reading_progress 表。确认current_page、total_page、updated_at字段值正确。再调一次接口确认不会触发数据库唯一键冲突。5.4 TTS 语音播报测试TTS 模块承接提醒播报需要在不同操作系统下测试一次。import pyttsx3 engine pyttsx3.init() engine.say(小可提醒你该去洗澡了) engine.runAndWait()运行后能听到语音说明本机 TTS 引擎链路正常。如果声音异常先调系统音量再检查音频驱动如果 pyttsx3 初始化报错优先确认espeak-ng是否安装。5.5 连续多次运行稳定性测试让服务跑 30 分钟连续创建 5 条相隔 2 分钟的提醒观察调度器是否都能触发。重点记录几个指标是否出现重复触发。是否出现任务丢失。数据库连接是否出现锁等待。日志文件增长是否正常。SQLite 在并发写入时可能出现database is locked建议在接口层增加重试机制或者把连接改成短连接避免跨请求持有连接。6. 接口 API 与批量任务整套服务以 REST API 为核心不依赖图形界面也能被外部工具调用。除了单条创建还需要批量导入能力。6.1 API 设计说明当前主程序已经提供了三个接口这里补一个批量创建提醒和批量导入书单的方案。批量操作的核心是循环请求加上失败重试不推荐一次性提交超大请求体。接口路径方法功能/api/remindersPOST创建单条提醒/api/remindersGET查询所有提醒/api/reminders/batchPOST批量创建提醒/api/reading/updatePOST更新阅读进度/api/reading/batch_importPOST批量导入书单6.2 批量创建提醒import requests url http://127.0.0.1:8000/api/reminders/batch payload [ {title: 小可该洗澡了, remind_time: 2025-02-01T22:00:00}, {title: 喝水提醒, remind_time: 2025-02-01T22:30:00}, {title: 关灯睡觉, remind_time: 2025-02-01T23:00:00}, ] response requests.post(url, jsonpayload, timeout10) print(response.status_code) print(response.json())后端可以按下面方式实现批量接口class BatchReminderCreate(BaseModel): items: list[ReminderCreate] app.post(/api/reminders/batch) def batch_create_reminders(batch: BatchReminderCreate): results [] for item in batch.items: try: result create_reminder(item) results.append({status: ok, data: result}) except Exception as exc: results.append({status: failed, error: str(exc)}) return results6.3 批量导入书单批量导入书单的目的是把本地 CSV 里的阅读计划一次性写入数据库。假设books.csv文件内容格式为书名,当前页码,总页码对应的导入脚本如下import csv import requests csv_path books.csv api_url http://127.0.0.1:8000/api/reading/batch_import items [] with open(csv_path, r, encodingutf-8) as f: reader csv.DictReader(f) for row in reader: items.append( { book_name: row[书名], current_page: int(row[当前页码]), total_page: int(row[总页码]), } ) response requests.post(api_url, json{items: items}, timeout30) print(response.json())批量任务的失败重试建议记录每个条目的索引和错误原因。只对返回failed的条目做重试不要整体重发。大批量导入时在服务端限制单次最多 100 条避免请求体过大。导入前先做数据合法性校验页码不能为负数总页数不能小于当前页数。6.4 API 鉴权与访问限制这一类本地服务如果不做鉴权局域网内任意设备都能调用接口存在安全隐患。建议在 Nginx 反向代理层加X-Api-Key校验或者直接在 FastAPI 里加一个简单的依赖注入中间件from fastapi import Header, HTTPException API_KEY your-local-api-key def verify_api_key(x_api_key: str Header(default)): if x_api_key ! API_KEY: raise HTTPException(status_code401, detailInvalid API Key)然后在需要保护的接口上加入dependencies[Depends(verify_api_key)]。这只是本地服务的基础防护如果有更强的安全需求建议接入完整的 OAuth2 或 JWT 方案。7. 资源占用与性能观察这类轻量服务的资源占用很低但如果接入本地语音模型情况会完全不同。可以从几个维度观察。7.1 基础服务占用以 FastAPI APScheduler SQLite pyttsx3 这套组合为例空跑时 CPU 占用接近 0内存占用通常在 80MB 到 200MB 之间具体取决于系统 Python 环境和依赖数量。查看方式# Linux / macOS top -p $(pgrep -f uvicorn app:app) # Windows tasklist | findstr python7.2 触发语音播报时占用语音播报使用的是系统 TTS 引擎播报瞬间 CPU 会有一个短暂上升内存基本不变。如果换成edge-tts在线合成资源占用会更低但需要联网且文本内容会经过第三方服务隐私性不如本地 TTS。7.3 接入本地 ASR/TTS 模型时占用如果后续要让“小可”支持语音对话比如先录音再识别再合成回复就需要评估本地模型。以 Whisper 系列模型为例whisper-tiny在 CPU 上也能跑但推理速度慢whisper-base和中型模型需要更多内存显存占用与否取决于你用的是 CPU 还是 GPU 版本。这一步不要凭空估算需要在真实机器上跑一次基准测试记录加载时间、推理时间和峰值内存。降低资源占用的几个方向提醒服务保持轻量不加载任何大模型只有需要语音识别时才按需加载。TTS 播报采用异步线程避免阻塞 API 响应。定期清理已完成的 reminders 历史记录避免 SQLite 表无限增长。定时任务使用持久化调度器服务重启后任务不丢失。7.4 日志与监控给app.py加日志输出观察服务运行状态import logging logging.basicConfig( filenamelogs/app.log, levellogging.INFO, format%(asctime)s - %(levelname)s - %(message)s, )在提醒触发、API 请求、数据库写入三个关键节点各写一条日志出问题时可以直接从日志文件定位。8. 常见问题与排查方法整个部署过程中最容易踩的坑集中在依赖安装、端口占用、TTS 无声、任务不触发、数据库锁这五类。整理成下表便于排查。问题现象可能原因排查方式解决方案uvicorn 启动失败提示端口被占用上一次服务未退出或其他程序占用 8000 端口检查端口占用进程更换端口启动或杀掉占用进程pip 安装 pyttsx3 失败Python 版本过高、缺少编译工具查看 pip 完整报错日志用 Python 3.10 虚拟环境或安装 binary 版本语音没有声音系统 TTS 引擎未安装、音量过低、pyttsx3 驱动异常单独运行 pyttsx3 测试脚本Linux 安装 espeak-ngWindows 检查音频服务定时任务没有触发时区不一致、run_date 时间格式错误、调度器未启动查看日志确认任务是否注册统一时区设置使用datetime.fromisoformat解析SQLite 报 database is locked多个线程同时写库查看完整异常堆栈改为短连接写操作加 retrySwagger 页面打不开/docs 路由未注册或服务未启动curl 请求 /docs 查看返回确认 FastAPI 实例声明正确批量导入时部分条目失败接口返回超时、CSV 格式错误逐条打印失败原因校验数据格式每批次控制在 100 条以内服务重启后定时任务丢失调度器未配置持久化查看 job 列表改用 APScheduler 的 SQLAlchemyJobStore服务没有响应时第一步先看日志不要盲目重启。日志里能直接看到异常栈、请求路径和数据库错误绝大多数问题定位成本会大幅降低。9. 最佳实践与使用建议9.1 保持最小可运行配置第一版不要急着加语音对话、人脸识别、微信推送这些功能。先跑通“创建提醒 - 定时触发 - TTS 播报 - 记录完成状态”的最小闭环确认调度和播报稳定后再逐步扩展。最小闭环稳定后后续加任何功能都不会影响核心链路。9.2 文件与数据管理项目目录按功能拆分database/存放 SQLite 数据库文件定期备份。logs/存放运行日志按日期切分。static/存放 Web 管理页面。scripts/存放批量导入和测试脚本。备份数据库最简单的方式是冷拷贝服务停止后复制.db文件。要保证数据一致性可以在备份前调用VACUUM INTO指令。9.3 接口调用与批量任务设计批量任务要遵循“小批次、快失败、可重试”的原则。不要把所有任务打包成一个超大请求应该由调用方循环分页提交。服务端对每个子任务单独捕获异常返回详细错误信息调用方根据status字段决定是否重试。9.4 复杂提醒规则设计简单日期触发可以满足定时提醒但如果要做“每天 22:00 提醒直到完成”就要改用 APScheduler 的cron触发器。注意区分一次性提醒和循环提醒避免任务重复生成。建议在数据库表中加一个remind_type字段值为once或cron触发逻辑按类型区分。9.5 授权与合规提醒涉及语音录制、声音克隆、家庭成员信息记录时应提前取得相关人员的明确同意。儿童的语音数据尤其敏感不要存入公共数据库不要用于模型微调。涉及书籍、文章内容导入的场景只保存元数据不保存受版权保护的作品全文。10. 总结与下一步这个项目最值得尝试的点是把“小可怎么还不洗澡”这种日常口头需求用一个 200 行左右的 Python 服务落地成可运行的提醒系统。建议你先验证两件事第一是 APScheduler 定时触发是否准确第二是 pyttsx3 语音播报在你的系统上是否能正常出声。这两个环节通了整个方案就已经及格。最容易被忽略的坑是时区。APScheduler 默认时区如果不显式指定提醒时间经常会偏移几个小时建议从一开始就在代码里固定timezoneAsia/Shanghai。另一个坑是 SQLite 多线程写锁本地服务并发量不大可能不遇到但一旦开始跑批量导入就要注意连接管理。后续扩展方向不用太复杂先加 Web 管理页面让不熟悉 curl 的人也能创建提醒再加语音识别让“小可”能听懂你说话最后再接入微信或钉钉推送作为 TTS 播报的补充通道。当前这套最小方案可以直接作为项目地基所有扩展都基于同一套 API 和数据模型不会造成结构返工。建议收藏备用按这个流程先把最小闭环跑起来再根据自己的设备条件逐项增强。 本地智能语音提醒助手：定时任务与语音播报的Python实现
这个标题其实是一段非常典型的“需求输入”“小可怎么还不洗澡”翻译成技术需求就是一条定时语音提醒任务“马上就看完这本书了我想先看完”翻译成技术需求就是阅读进度跟踪与延迟执行逻辑。把这两句话放到一起看它就是一个很接地气的本地智能语音助手场景到点提醒、状态记录、延后处理。这篇文章要讨论的不是什么大模型推理框架而是一套可以直接落地运行的本地语音提醒助手完整方案。我会从需求拆解开始给出环境准备、接口设计、批量任务、性能观察和排错清单带你把这个“一句话需求”变成一个能用的服务。项目原理不复杂普通电脑就能跑重点在于把调度、存储、语音播报和 Web 管理端串起来。1. 核心能力速览先看这套方案要实现的整体能力。以下表格里的参数属于通用推荐值实际运行效果需要结合本机环境验证。能力项说明项目类型本地智能语音提醒助手服务核心功能定时提醒语音播报、阅读进度记录、延后提醒、Web 管理端硬件门槛普通 PC 即可无需独立显卡若接入本地 ASR/TTS 模型则需按模型评估运行平台Windows / Linux / macOS主要技术栈Python、FastAPI、APScheduler、SQLite、pyttsx3启动方式命令行启动 Web 服务浏览器访问管理页面接口能力提供 REST API支持创建提醒、查询任务、更新进度、批量导入书单批量任务支持书单批量导入、批量创建定时提醒实时语音播报依赖系统自带 TTS 引擎离线可用适合场景家庭个人提醒、阅读管理、学习计划、轻量自动化任务这套方案最大的优势是不依赖昂贵的云服务提醒任务、阅读进度、历史记录都存在本地数据库里。你只需要一个 Python 环境就能把服务跑起来并通过浏览器或 API 方式管理所有任务。2. 适用场景与使用边界先明确它适合谁。最典型的用户是个人和家庭场景你想让电脑在晚上 10 点提醒孩子洗澡但你正在看书希望把提醒延后 20 分钟同时记录当前阅读进度这么一套交互流程正好可以被这套服务覆盖。它适合解决的问题包括三类定时提醒类比如“小可怎么还不洗澡”“该站起来活动了”“药快吃完了”。阅读进度类记录每本书读到了多少页、剩余多少页、当前状态是“在读”还是“已完成”。延后处理类收到提醒后选择“再等 10 分钟”“我正在看书再放一会儿”系统自动重新排队提醒。不适合的场景也要说清楚。它不适合用来做无授权的公共环境录音、不适合在未告知家人的情况下采集语音数据也不需要接入任何云语音识别能力的时候优先保证隐私不出本机。如果后续扩展语音识别和语音克隆功能必须取得目标对象授权尤其是儿童和家庭成员的声音素材不能随意录入和传播。在合规层面使用 TTS 播报内容时要确保提醒文本不包含冒犯性、歧视性内容批量导入书单时也要注意书籍内容的版权边界只保留个人阅读元数据不存储整本受版权保护的电子书内容。3. 环境准备与前置条件这套服务对硬件要求极低重点在软件环境。我的建议是先跑最小闭环再逐步加语音识别模型。3.1 操作系统与运行时Windows 10/11、Ubuntu 20.04 及以上、macOS 12 及以上都可以。需要 Python 3.10 或更高版本安装完 Python 后确认 pip 可用python --version pip --version如果系统同时装了多个 Python 版本建议用python3和pip3命令做区分。3.2 需要安装的依赖核心依赖包括 FastAPI、Uvicorn、APScheduler、SQLAlchemy、pyttsx3。如果你要用浏览器调试 REST APIFastAPI 自带的 Swagger 文档页可以直接用不需要额外安装。fastapi uvicorn apscheduler sqlalchemy pyttsx3Linux 系统使用 pyttsx3 之前需要安装语音合成引擎。Ubuntu/Debian 系可以运行下面的命令Windows 和 macOS 一般直接可用sudo apt update sudo apt install espeak-ng libespeak-ng13.3 项目目录结构建议把项目统一放在一个目录下后续模型文件、日志、数据库分离管理。xiaoke_assistant/ ├── app.py ├── requirements.txt ├── database/ │ └── assistant.db ├── logs/ │ └── app.log └── static/ └── index.htmlassistant.db是 SQLite 数据库文件首次启动后自动生成logs/app.log记录服务运行日志和定时任务执行情况。3.4 端口检查服务默认监听8000端口。启动前检查端口是否被占用# Windows netstat -ano | findstr :8000 # Linux / macOS lsof -i :8000如果端口被占用可以在启动命令里指定新的端口后续所有访问地址同步修改。4. 安装部署与启动方式部署过程不复杂核心就是把依赖装好、把服务启动起来。下面先给出一份可用的主程序示例再说明启动步骤。4.1 创建虚拟环境并安装依赖在项目根目录执行cd xiaoke_assistant python -m venv venv # Windows venv\Scripts\activate # Linux / macOS source venv/bin/activate pip install -r requirements.txt4.2 主程序实现app.py里实现三个层面的功能定时调度器、数据库模型、REST API。下面是一个可直接用的最小版本覆盖提醒创建、提醒列表、阅读进度更新和语音播报触发。import sqlite3 import threading from datetime import datetime, timedelta from apscheduler.schedulers.background import BackgroundScheduler from fastapi import FastAPI, HTTPException from pydantic import BaseModel app FastAPI(title小可语音提醒助手, version0.1.0) scheduler BackgroundScheduler(timezoneAsia/Shanghai) scheduler.start() DB_PATH database/assistant.db def init_db(): conn sqlite3.connect(DB_PATH) cursor conn.cursor() cursor.execute( CREATE TABLE IF NOT EXISTS reminders ( id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL, remind_time TEXT NOT NULL, status TEXT DEFAULT pending, created_at TEXT DEFAULT CURRENT_TIMESTAMP ) ) cursor.execute( CREATE TABLE IF NOT EXISTS reading_progress ( id INTEGER PRIMARY KEY AUTOINCREMENT, book_name TEXT NOT NULL, current_page INTEGER DEFAULT 0, total_page INTEGER DEFAULT 0, status TEXT DEFAULT reading, updated_at TEXT DEFAULT CURRENT_TIMESTAMP ) ) conn.commit() conn.close() class ReminderCreate(BaseModel): title: str remind_time: str delay_minutes: int 0 class ReadingProgressUpdate(BaseModel): book_name: str current_page: int total_page: int def speak_text(text: str): try: import pyttsx3 engine pyttsx3.init() engine.say(text) engine.runAndWait() except Exception as exc: print(f[TTS 错误] {exc}) def trigger_reminder(reminder_id: int, title: str): print(f[执行提醒] {datetime.now()} - {title}) speak_text(f小可提醒你{title}) conn sqlite3.connect(DB_PATH) cursor conn.cursor() cursor.execute( UPDATE reminders SET status done WHERE id ?, (reminder_id,) ) conn.commit() conn.close() app.on_event(startup) def startup_event(): init_db() app.post(/api/reminders) def create_reminder(item: ReminderCreate): remind_time item.remind_time if item.delay_minutes 0: delay datetime.fromisoformat(remind_time) timedelta(minutesitem.delay_minutes) remind_time delay.isoformat() conn sqlite3.connect(DB_PATH) cursor conn.cursor() cursor.execute( INSERT INTO reminders (title, remind_time) VALUES (?, ?), (item.title, remind_time), ) conn.commit() reminder_id cursor.lastrowid conn.close() run_date datetime.fromisoformat(remind_time) scheduler.add_job( trigger_reminder, triggerdate, run_daterun_date, args[reminder_id, item.title], idfreminder_{reminder_id}, replace_existingTrue, ) return {id: reminder_id, title: item.title, remind_time: remind_time} app.get(/api/reminders) def list_reminders(): conn sqlite3.connect(DB_PATH) cursor conn.cursor() cursor.execute(SELECT id, title, remind_time, status FROM reminders ORDER BY remind_time DESC) rows cursor.fetchall() conn.close() return [ {id: row[0], title: row[1], remind_time: row[2], status: row[3]} for row in rows ] app.post(/api/reading/update) def update_reading_progress(item: ReadingProgressUpdate): conn sqlite3.connect(DB_PATH) cursor conn.cursor() cursor.execute( INSERT INTO reading_progress (book_name, current_page, total_page, status) VALUES (?, ?, ?, ?) , (item.book_name, item.current_page, item.total_page, reading), ) conn.commit() conn.close() return {message: 阅读进度已更新, book_name: item.book_name}启动服务uvicorn app:app --host 0.0.0.0 --port 8000启动后终端输出Uvicorn running on http://0.0.0.0:8000浏览器打开http://127.0.0.1:8000/docs就能看到 Swagger 接口文档页这是一个很好的功能自测入口。如果希望局域网内其他设备也能访问把host参数改为0.0.0.0即可但要注意服务不设鉴权时不要暴露在公网。4.3 验证服务是否正常在另一个终端执行curl http://127.0.0.1:8000/docs返回 HTML 内容说明服务正常。看到 404 则说明路由冲突检查是否在错误的目录启动了 uvicorn。5. 功能测试与效果验证服务启动后按照下面的顺序做一轮功能验证。每一类测试都包含预期结果和判断标准。5.1 创建定时提醒测试目标是确认提醒任务能写入数据库并且能被 APScheduler 调度。curl -X POST http://127.0.0.1:8000/api/reminders \ -H Content-Type: application/json \ -d {title: 小可该洗澡了, remind_time: 2025-02-01T22:00:00}预期返回{ id: 1, title: 小可该洗澡了, remind_time: 2025-02-01T22:00:00 }这时把系统时间手动调整到接近提醒时间或者把remind_time设置为当前时间之后 1 分钟观察终端是否打印[执行提醒]同时系统扬声器是否有语音播报。判断成功的标准数据库 reminders 表出现新记录。到达提醒时间后状态从pending更新为done。终端有提醒日志输出。TTS 引擎播报“小可提醒你小可该洗澡了”。常见失败点有两个一是datetime.fromisoformat无法解析带时区的字符串二是 APScheduler 默认时区和系统时区不一致导致任务提前或延后触发。建议代码里统一使用timezoneAsia/Shanghai。5.2 延后提醒测试延后提醒对应标题里的“马上就看完这本书了我想先看完”。其逻辑是收到提醒后把执行时间往后推一段时间。curl -X POST http://127.0.0.1:8000/api/reminders \ -H Content-Type: application/json \ -d {title: 小可该洗澡了延后20分钟, remind_time: 2025-02-01T22:00:00, delay_minutes: 20}预期remind_time返回2025-02-01T22:20:00DB 里存储的是延后后的时间。你可以通过查看响应内容判断延后逻辑是否生效。如果延后提醒需要支持“只延后一次”还是“每次都延后”需要再加一个delay_count字段和判断逻辑这里先跑通单次延后。5.3 阅读进度更新测试阅读进度管理是另一个核心功能。每次看书暂停后调一次接口记录当前页码。curl -X POST http://127.0.0.1:8000/api/reading/update \ -H Content-Type: application/json \ -d {book_name: 三体, current_page: 128, total_page: 302}预期返回{ message: 阅读进度已更新, book_name: 三体 }验证方法打开 SQLite 数据库查看 reading_progress 表。确认current_page、total_page、updated_at字段值正确。再调一次接口确认不会触发数据库唯一键冲突。5.4 TTS 语音播报测试TTS 模块承接提醒播报需要在不同操作系统下测试一次。import pyttsx3 engine pyttsx3.init() engine.say(小可提醒你该去洗澡了) engine.runAndWait()运行后能听到语音说明本机 TTS 引擎链路正常。如果声音异常先调系统音量再检查音频驱动如果 pyttsx3 初始化报错优先确认espeak-ng是否安装。5.5 连续多次运行稳定性测试让服务跑 30 分钟连续创建 5 条相隔 2 分钟的提醒观察调度器是否都能触发。重点记录几个指标是否出现重复触发。是否出现任务丢失。数据库连接是否出现锁等待。日志文件增长是否正常。SQLite 在并发写入时可能出现database is locked建议在接口层增加重试机制或者把连接改成短连接避免跨请求持有连接。6. 接口 API 与批量任务整套服务以 REST API 为核心不依赖图形界面也能被外部工具调用。除了单条创建还需要批量导入能力。6.1 API 设计说明当前主程序已经提供了三个接口这里补一个批量创建提醒和批量导入书单的方案。批量操作的核心是循环请求加上失败重试不推荐一次性提交超大请求体。接口路径方法功能/api/remindersPOST创建单条提醒/api/remindersGET查询所有提醒/api/reminders/batchPOST批量创建提醒/api/reading/updatePOST更新阅读进度/api/reading/batch_importPOST批量导入书单6.2 批量创建提醒import requests url http://127.0.0.1:8000/api/reminders/batch payload [ {title: 小可该洗澡了, remind_time: 2025-02-01T22:00:00}, {title: 喝水提醒, remind_time: 2025-02-01T22:30:00}, {title: 关灯睡觉, remind_time: 2025-02-01T23:00:00}, ] response requests.post(url, jsonpayload, timeout10) print(response.status_code) print(response.json())后端可以按下面方式实现批量接口class BatchReminderCreate(BaseModel): items: list[ReminderCreate] app.post(/api/reminders/batch) def batch_create_reminders(batch: BatchReminderCreate): results [] for item in batch.items: try: result create_reminder(item) results.append({status: ok, data: result}) except Exception as exc: results.append({status: failed, error: str(exc)}) return results6.3 批量导入书单批量导入书单的目的是把本地 CSV 里的阅读计划一次性写入数据库。假设books.csv文件内容格式为书名,当前页码,总页码对应的导入脚本如下import csv import requests csv_path books.csv api_url http://127.0.0.1:8000/api/reading/batch_import items [] with open(csv_path, r, encodingutf-8) as f: reader csv.DictReader(f) for row in reader: items.append( { book_name: row[书名], current_page: int(row[当前页码]), total_page: int(row[总页码]), } ) response requests.post(api_url, json{items: items}, timeout30) print(response.json())批量任务的失败重试建议记录每个条目的索引和错误原因。只对返回failed的条目做重试不要整体重发。大批量导入时在服务端限制单次最多 100 条避免请求体过大。导入前先做数据合法性校验页码不能为负数总页数不能小于当前页数。6.4 API 鉴权与访问限制这一类本地服务如果不做鉴权局域网内任意设备都能调用接口存在安全隐患。建议在 Nginx 反向代理层加X-Api-Key校验或者直接在 FastAPI 里加一个简单的依赖注入中间件from fastapi import Header, HTTPException API_KEY your-local-api-key def verify_api_key(x_api_key: str Header(default)): if x_api_key ! API_KEY: raise HTTPException(status_code401, detailInvalid API Key)然后在需要保护的接口上加入dependencies[Depends(verify_api_key)]。这只是本地服务的基础防护如果有更强的安全需求建议接入完整的 OAuth2 或 JWT 方案。7. 资源占用与性能观察这类轻量服务的资源占用很低但如果接入本地语音模型情况会完全不同。可以从几个维度观察。7.1 基础服务占用以 FastAPI APScheduler SQLite pyttsx3 这套组合为例空跑时 CPU 占用接近 0内存占用通常在 80MB 到 200MB 之间具体取决于系统 Python 环境和依赖数量。查看方式# Linux / macOS top -p $(pgrep -f uvicorn app:app) # Windows tasklist | findstr python7.2 触发语音播报时占用语音播报使用的是系统 TTS 引擎播报瞬间 CPU 会有一个短暂上升内存基本不变。如果换成edge-tts在线合成资源占用会更低但需要联网且文本内容会经过第三方服务隐私性不如本地 TTS。7.3 接入本地 ASR/TTS 模型时占用如果后续要让“小可”支持语音对话比如先录音再识别再合成回复就需要评估本地模型。以 Whisper 系列模型为例whisper-tiny在 CPU 上也能跑但推理速度慢whisper-base和中型模型需要更多内存显存占用与否取决于你用的是 CPU 还是 GPU 版本。这一步不要凭空估算需要在真实机器上跑一次基准测试记录加载时间、推理时间和峰值内存。降低资源占用的几个方向提醒服务保持轻量不加载任何大模型只有需要语音识别时才按需加载。TTS 播报采用异步线程避免阻塞 API 响应。定期清理已完成的 reminders 历史记录避免 SQLite 表无限增长。定时任务使用持久化调度器服务重启后任务不丢失。7.4 日志与监控给app.py加日志输出观察服务运行状态import logging logging.basicConfig( filenamelogs/app.log, levellogging.INFO, format%(asctime)s - %(levelname)s - %(message)s, )在提醒触发、API 请求、数据库写入三个关键节点各写一条日志出问题时可以直接从日志文件定位。8. 常见问题与排查方法整个部署过程中最容易踩的坑集中在依赖安装、端口占用、TTS 无声、任务不触发、数据库锁这五类。整理成下表便于排查。问题现象可能原因排查方式解决方案uvicorn 启动失败提示端口被占用上一次服务未退出或其他程序占用 8000 端口检查端口占用进程更换端口启动或杀掉占用进程pip 安装 pyttsx3 失败Python 版本过高、缺少编译工具查看 pip 完整报错日志用 Python 3.10 虚拟环境或安装 binary 版本语音没有声音系统 TTS 引擎未安装、音量过低、pyttsx3 驱动异常单独运行 pyttsx3 测试脚本Linux 安装 espeak-ngWindows 检查音频服务定时任务没有触发时区不一致、run_date 时间格式错误、调度器未启动查看日志确认任务是否注册统一时区设置使用datetime.fromisoformat解析SQLite 报 database is locked多个线程同时写库查看完整异常堆栈改为短连接写操作加 retrySwagger 页面打不开/docs 路由未注册或服务未启动curl 请求 /docs 查看返回确认 FastAPI 实例声明正确批量导入时部分条目失败接口返回超时、CSV 格式错误逐条打印失败原因校验数据格式每批次控制在 100 条以内服务重启后定时任务丢失调度器未配置持久化查看 job 列表改用 APScheduler 的 SQLAlchemyJobStore服务没有响应时第一步先看日志不要盲目重启。日志里能直接看到异常栈、请求路径和数据库错误绝大多数问题定位成本会大幅降低。9. 最佳实践与使用建议9.1 保持最小可运行配置第一版不要急着加语音对话、人脸识别、微信推送这些功能。先跑通“创建提醒 - 定时触发 - TTS 播报 - 记录完成状态”的最小闭环确认调度和播报稳定后再逐步扩展。最小闭环稳定后后续加任何功能都不会影响核心链路。9.2 文件与数据管理项目目录按功能拆分database/存放 SQLite 数据库文件定期备份。logs/存放运行日志按日期切分。static/存放 Web 管理页面。scripts/存放批量导入和测试脚本。备份数据库最简单的方式是冷拷贝服务停止后复制.db文件。要保证数据一致性可以在备份前调用VACUUM INTO指令。9.3 接口调用与批量任务设计批量任务要遵循“小批次、快失败、可重试”的原则。不要把所有任务打包成一个超大请求应该由调用方循环分页提交。服务端对每个子任务单独捕获异常返回详细错误信息调用方根据status字段决定是否重试。9.4 复杂提醒规则设计简单日期触发可以满足定时提醒但如果要做“每天 22:00 提醒直到完成”就要改用 APScheduler 的cron触发器。注意区分一次性提醒和循环提醒避免任务重复生成。建议在数据库表中加一个remind_type字段值为once或cron触发逻辑按类型区分。9.5 授权与合规提醒涉及语音录制、声音克隆、家庭成员信息记录时应提前取得相关人员的明确同意。儿童的语音数据尤其敏感不要存入公共数据库不要用于模型微调。涉及书籍、文章内容导入的场景只保存元数据不保存受版权保护的作品全文。10. 总结与下一步这个项目最值得尝试的点是把“小可怎么还不洗澡”这种日常口头需求用一个 200 行左右的 Python 服务落地成可运行的提醒系统。建议你先验证两件事第一是 APScheduler 定时触发是否准确第二是 pyttsx3 语音播报在你的系统上是否能正常出声。这两个环节通了整个方案就已经及格。最容易被忽略的坑是时区。APScheduler 默认时区如果不显式指定提醒时间经常会偏移几个小时建议从一开始就在代码里固定timezoneAsia/Shanghai。另一个坑是 SQLite 多线程写锁本地服务并发量不大可能不遇到但一旦开始跑批量导入就要注意连接管理。后续扩展方向不用太复杂先加 Web 管理页面让不熟悉 curl 的人也能创建提醒再加语音识别让“小可”能听懂你说话最后再接入微信或钉钉推送作为 TTS 播报的补充通道。当前这套最小方案可以直接作为项目地基所有扩展都基于同一套 API 和数据模型不会造成结构返工。建议收藏备用按这个流程先把最小闭环跑起来再根据自己的设备条件逐项增强。