库存语音助手
免提、本地托管的语音界面 灵通无绳。当你在箱子和盒子里实际分类时，与目录中的物品交谈——不要打字，也不要点击。一切都在你自己的硬件上运行；没有什么离开你的网络。
运作原理
你说话。助理转录你的演讲（Whisper），理解你的意图（通过llama.cpp的本地LLM），通过其REST API更新Homebox，并读回发生了什么变化（Kokoro TTS）。一个小型的FastAPI服务将它们连接在一起，并为单页UI提供服务。
Browser ──▶ inventory-api ──▶ Whisper (speech → text)
──▶ llama.cpp (text → tool calls)
──▶ Homebox (inventory writes)
──▶ Kokoro (text → speech)会话是有状态的：助手会记住您的当前位置并维护一个撤消堆栈，这样错误就很容易修复。
______________________________________________________________________
先决条件
- Docker Compose 使用Docker Compose插件(
docker compose) - 英伟达GPU --whisper和llama.cpp都使用CUDA。这
nvidia-container-toolkit必须安装并工作(docker run --gpus all nvidia/cuda:12-base nvidia-smi应该成功） - 跑步 灵通无绳 实例（包含在编写文件中，或指向现有实例）
- A. GGUF模型文件 使用工具调用支持--请参阅 模型选择 在......下面
______________________________________________________________________
快速开始
1.克隆和配置
git clone https://github.com/cyberlightdev/inventory-voice-assistant
cd inventory-voice-assistant
cp .env.example .env编辑 .env:
HOMEBOX_EMAIL=you@example.com
HOMEBOX_PASSWORD=your-password
LLAMA_CPP_MODEL=model.gguf # filename only — file must be in the repo root
MMPROJ_MODEL= # optional: mmproj GGUF for vision support
WHISPER_MODEL=small # tiny | base | small | medium | large-v3
KOKORO_VOICE=af_sky # see Voice options below
HISTORY_TURNS=6 # conversation turns kept in context2.放置模型文件
将GGUF文件放入repo根目录（与 docker-compose.yml).组合文件挂载 .:/models 所以llama.cpp可以找到它们。
3.开始
docker compose up -d打开 http://localhost:4004 在您的浏览器中。在提示时授予麦克风权限。
______________________________________________________________________
使用预构建的图像
标记的版本会自动发布到GHCR。使用预构建 inventory-api 图像而不是本地构建，替换 build: 线路输入 docker-compose.yml:
inventory-api:
image: ghcr.io/cyberlightdev/inventory-voice-assistant:latest
# build: ./inventory-api ← remove or comment out然后拉动并启动：
docker compose pull inventory-api
docker compose up -d______________________________________________________________________
模型选择
LLM必须支持 OpenAI兼容的工具/函数调用 通过llama.cpp的服务器。推荐型号（量化GGUF、Q4_K_M或更好）：
| 型号 | 备注 |
|---|---|
| Qwen3 （任何尺寸） | 出色的工具使用； --chat-template-kwargs '{"enable_thinking":false}' 已在compose中设置为抑制思维标记 |
| Mistral 7B说明书 | 可靠的工具调用，较低的VRAM |
| Llama 3.1/3.2说明书 | 8B时工具使用能力强 |
| 杰玛3 | 更紧凑的VRAM预算的好选择 |
注： 如果您使用的是非Qwen3型号，则可能需要删除--chat-template-kwargs从中的llama cpp命令docker-compose.yml该标志是Qwen3特有的，其他型号会忽略或处理不当。
从下载GGUF文件 拥抱脸.放置在repo根目录中并设置 LLAMA_CPP_MODEL=yourfile.gguf 在 .env.
______________________________________________________________________
视觉支持
要启用相机按钮（将照片附加到下一条语音信息中）：
- 下载匹配项 mmproj GGUF适用于您的模型（可与Hugging Face上的基本GGUF一起使用——查找包含以下内容的文件
mmproj在名称中） - 将其放置在repo根目录中
- 集
MMPROJ_MODEL=mmproj-yourfile.gguf在.env - 重新启动llama cpp：
docker compose restart llama-cpp
您还可以通过设置UI配置mmproj模型(⚙ 图标）。当未配置mmproj型号时，相机按钮会自动禁用。
______________________________________________________________________
对话模式
坚持说话
按住 按住说话 按钮（或 Space)记录。发布以提交。
会话模式
点击 卷积模式 以实现连续收听。VAD（语音活动检测）会自动检测语音，并在您暂停时提交。
唤醒词 （可选）：在设置中设置唤醒词（例如。 hey box).设置后，助手会忽略所有音频，直到听到唤醒词。一旦激活：
- 播放一个简短的升调——会话已打开
- 您可以在不重复唤醒词的情况下自由发出命令30秒
- 沉默30秒后，会播放一个下降的音调，会议结束
______________________________________________________________________
语音命令
助手理解自然语言并将其映射到以下动作：
| 你说什么 | 会发生什么 |
|---|---|
| “将位置设置为车库货架三” | 创建或切换到该位置 |
| “添加锤子”/“找到五个拉链” | 将项目添加到当前位置 |
| “实际上有三个，而不是五个” | 将数量更新为绝对值 |
| “将钻机移动到车间” | 将项目移动到另一个位置 |
| “我的XLR电缆在哪里？” | 搜索所有位置 |
| “我有哪些位置？” | 列出所有位置 |
| “撤消”/“错了”/“没关系” | 反转最后一个动作（最多5个深度） |
| “移除损坏的货架支架” | 完全删除一个项目 |
______________________________________________________________________
设置
所有设置均可通过访问 ⚙ 右上角的图标。更改会立即应用，无需重新启动容器，但以下情况除外：
- LLM模型（GGUF）：需要
docker compose restart llama-cpp - 视觉投影仪（mmproj）：需要
docker compose restart llama-cpp
设置将保留到 ./config/settings.json （安装到容器中）并在容器重启后存活。
语音选项
Whisper型号 （语音识别）：
| 型号 | VRAM | 备注 |
|---|---|---|
tiny | 约250 MB | 速度最快，精度最低 |
base | 约300 MB | |
small | ~500 MB | 余额良好（默认） |
medium | 约1.5gb | |
large-v3 | 约3 GB | 最佳精度 |
科科罗的声音 （文本转语音）：
| 语音 | 描述 |
|---|---|
af_sky | 美国女性（默认） |
af_bella | 美国女性 |
am_adam | 美国男性 |
am_michael | 美国男性 |
bf_emma | 英国女性 |
bm_george | 英国男性 |
______________________________________________________________________
发展
要在本地构建和运行实时代码更改：
# Build the inventory-api image from source
docker compose up --build inventory-api
# Or mount index.html for live UI edits without rebuilding:
# Add to docker-compose.yml volumes:
# - ./inventory-api/index.html:/app/index.html项目布局：
inventory-api/
Dockerfile
requirements.txt
main.py — FastAPI app, chat loop, config, audio proxies
homebox_client.py — Sync Homebox REST API wrapper
tools.py — 9 tool functions + OpenAI JSON schemas
index.html — Single-page UI (served by FastAPI)
docker-compose.yml
.env.example释放
按下semver标签以触发GHCR构建：
git tag v1.0.0
git push origin v1.0.0工作流发布 ghcr.io/cyberlightdev/inventory-voice-assistant:1.0.0, :1.0，以及 :latest.
______________________________________________________________________
建筑说明
- 无外部依赖关系：所有推理（ASR、LLM、TTS）都在本地硬件上运行
- 会话状态 内存中：正在重新启动
inventory-api清除对话历史记录，但不清除Homebox数据 - 配置分层：环境变量（来自
.env通过docker compose）在首次启动时设置默认值；设置UI写入./config/settings.json这将在后续启动时覆盖它们 - 刀具循环：聊天端点最多运行10 LLM→放弃前每个用户消息的工具调用迭代次数
- 历史修剪：只有系统提示+最后N个回合对被发送到LLM（可配置，默认6回合）
______________________________________________________________________
许可证
麻省理工学院