docs: 更新开发日志和本地部署经验，记录全双工实现细节

docs/开发日志.md

@@ -218,3 +218,75 @@ PregoPal/
 - **Emoji 只在 UI 标签中使用，不在数据/图表中**：避免 matplotlib 渲染乱码
 - **首页极简主义**：一个 Chatbot + 一个表格，无冗余卡片，聚焦对话
 - **字体自适应**：`font-family:inherit` 让所有 HTML 内联内容跟随 Gradio Soft 主题字体
+
+## 2026-06-10 全双工语音对话实现（llama.cpp-omni）
+
+### 背景
+PregoPal 原有的 AI 模块全部是占位符（raise NotImplementedError），核心层 core/ 只有空接口。本次改造利用本地 RTX 4060Ti 16GB 部署的 llama.cpp-omni 实现真正的全双工语音交互。
+
+### 模型文件
+位于 C:\Users\Andre\codes\LJB\llama.cpp-omni\models\
+- MiniCPM-o-4_5-Q4_K_M.gguf (4.68GB) — 主模型
+- vision/MiniCPM-o-4_5-vision-F16.gguf (1.04GB) — 视觉投影
+- audio/MiniCPM-o-4_5-audio-F16.gguf (630MB) — 音频投影
+- tts/ — TTS 模型 (1.16GB) + projector (15MB)
+- token2wav-gguf/ — token2wav 组件 (~890MB)
+
+### llama.cpp-omni 端点
+| 端点 | 作用 |
+|------|------|
+| POST /v1/stream/omni_init | 初始化 omni context |
+| POST /v1/stream/reset | 重置 KV cache |
+| POST /v1/stream/prefill | 音频/图像 token 填充 |
+| POST /v1/stream/decode | 解码输出文本+TTS token |
+| POST /v1/stream/break | 打断生成 |
+
+### 全双工架构
+用户说话 → Gradio gr.Audio 录音 → voice_helper.py → PregoAPI(FastAPI:8090) → llama-server omni(:8081) → omni_init → prefill(WAV)→ decode → llm_text(chunks)+TTS WAV(chunks) → 文本+音频 base64 → Gradio聊天框+语音播放
+
+### 关键文件（本次新增/修改）
+- api/go_server.py — FastAPI 全双工后端，封装 /v1/omni/voice_chat
+- api/voice_helper.py — Python API 封装 (chat_text/chat_voice)
+- core/model_loader.py — 支持 chat + voice_chat 双模式
+- core/conversation_manager.py — 系统提示词 + 结构化标记解析
+- ui/app_builder.py — Gradio 语音对话 UI
+- start_services.py — 一键启动脚本
+
+### 显存管控 (RTX 4060Ti 16GB)
+- token2wav_device=cpu — token2wav 放 CPU
+- tts_gpu_layers=0 — TTS 不放 GPU
+- omni_init 后显存约 10.9GB/16GB (余量 5GB)
+
+### 启动命令
+```powershell
+# 1. llama-server
+C:\Users\Andre\codes\LJB\llama.cpp-omni\build\bin\Release\llama-server.exe -m C:\Users\Andre\codes\LJB\llama.cpp-omni\models\MiniCPM-o-4_5-Q4_K_M.gguf --mmproj C:\Users\Andre\codes\LJB\llama.cpp-omni\models\vision\MiniCPM-o-4_5-vision-F16.gguf -c 8192 --temp 0.7 --host 127.0.0.1 --port 8081 -ngl 99
+
+# 2. PregoAPI
+$env:LLAMA_SERVER_URL="http://127.0.0.1:8081"
+$env:OMNI_OUTPUT_DIR="C:\Users\Andre\codes\LJB\hackthon\for_qclaw_llamacpp\PregoPal\omni_output"
+C:\Users\Andre\miniconda3\envs\trader_stable\python.exe api\go_server.py
+
+# 3. Gradio
+C:\Users\Andre\miniconda3\envs\trader_stable\python.exe app.py
+```
+
+### 端到端测试
+```python
+import base64, requests, soundfile as sf, numpy as np, io
+sr = 16000; t = np.linspace(0, 1.0, sr); audio = (0.3*np.sin(2*np.pi*200*t)).astype(np.float32)
+buf = io.BytesIO(); sf.write(buf, audio, sr, format='WAV', subtype='PCM_16')
+b64 = base64.b64encode(buf.getvalue()).decode()
+r = requests.post('http://127.0.0.1:8090/v1/omni/voice_chat', json={'audio_base64':b64,'sample_rate':sr,'max_tokens':300}, timeout=600)
+print(r.json().get('text',''))
+```
+
+### 踩坑记录
+1. omni_init OOM: token2wav_device=cpu + tts_gpu_layers=0
+2. decode 卡死后 reset 超时: 重启 llama-server
+3. llm_text.txt 在 chunk_X/ 下: 修复→_read_llm_text() 合并所有 chunk
+4. TTS 只返回第一个 wav: 修复→_merge_wavs_to_base64() 合并全部 wav
+
+### Git
+仓库: C:\Users\Andre\codes\LJB\hackthon\for_qclaw_llamacpp\PregoPal
+关键提交: f54083c

docs/本地部署经验.md

@@ -72,3 +72,108 @@
 - **结果**：成功识别图片中的 "↓买入" 图标并输出中文描述 ✓
 - **加载时间**：约 **4 秒**（GPU CUDA）✓
 - **警告**：`n_ctx_seq (4096) < n_ctx_train (40960)` — 不影响功能
+
+---
+
+## llama.cpp-omni 本地全双工部署（2026-06-10 添加）
+
+### 项目目标
+利用本地 RTX 4060Ti 16GB 部署的 llama.cpp-omni 实现 MiniCPM-o 4.5 的全双工语音交互，将 PregoPal 从占位模式升级为真正的 AI 驱动孕期陪护应用。
+
+### 环境
+- GPU: NVIDIA GeForce RTX 4060 Ti (16GB VRAM)
+- OS: Windows 11
+- Python: trader_stable (3.11.15)
+- llama.cpp: omni 分支 (build 38, commit 891e0b1)
+
+### 源码编译（llama.cpp-omni）
+```powershell
+cd C:\Users\Andre\codes\LJB\llama.cpp-omni
+mkdir build && cd build
+cmake .. -DGGML_CUDA=ON -DCMAKE_BUILD_TYPE=Release -DLLAMA_BUILD_SERVER=ON
+cmake --build . --config Release -j
+```
+
+关键：源码中包含 omni/ 目录（全双工扩展），cmake 会自动编译 omni.dll + 链接到 server。
+
+### 启动 llama-server（含 omni 模式）
+```powershell
+# 关键参数：必须指定 vision mmproj，否则 omni_init 会崩溃
+$server = "C:\Users\Andre\codes\LJB\llama.cpp-omni\build\bin\Release\llama-server.exe"
+$modelDir = "C:\Users\Andre\codes\LJB\llama.cpp-omni\models"
+& $server -m "$modelDir\MiniCPM-o-4_5-Q4_K_M.gguf" `
+  --mmproj "$modelDir\vision\MiniCPM-o-4_5-vision-F16.gguf" `
+  -c 8192 --temp 0.7 --host 127.0.0.1 --port 8081 -ngl 99
+```
+
+### omni 初始化（关键步骤）
+```python
+import requests
+base = "http://127.0.0.1:8081"
+init_data = {
+    "media_type": 2,           # audio 模式
+    "use_tts": True,           # 开启 TTS
+    "duplex_mode": False,      # 先用半双工
+    "token2wav_device": "cpu", # ★ 关键：token2wav 放 CPU 节省显存
+    "tts_gpu_layers": 0,       # ★ 关键：TTS 不放 GPU
+}
+r = requests.post(f"{base}/v1/stream/omni_init", json=init_data, timeout=120)
+assert r.status_code == 200 and r.json()["success"]
+```
+
+### 全双工 pipeline
+1. omni_init — 加载 audio + TTS + token2wav 模块
+2. prefill — 传入 16kHz WAV 音频路径，编码为音频 token
+3. decode — 模型生成文本 token + TTS token
+4. TTS 输出 — 多个 wav_X.wav 文件生成到 output_dir/round_NNN/tts_wav/
+5. 文本输出 — 多个 chunk_X/llm_text.txt 生成到 output_dir/round_NNN/llm_debug/
+
+### 输出文件结构
+```
+omni_output/round_NNN/
+├── llm_debug/
+│   ├── chunk_0/llm_text.txt    # 文本片段
+│   ├── chunk_1/llm_text.txt
+│   └── ...                      # 8-10 个 chunk
+└── tts_wav/
+    ├── wav_0.wav                # TTS 音频片段
+    ├── wav_1.wav
+    ├── wav_20.wav               # ~21 个 wav
+    └── generation_done.flag    # 完成标志
+```
+
+### API 封装（PregoAPI）
+`api/go_server.py` 封装了 FastAPI 后端，暴露：
+- GET /health — 健康检查（含 omni 初始化状态）
+- POST /v1/chat/completions — 文本对话（proxy 到 llama-server）
+- POST /v1/omni/voice_chat — 全双工语音对话（核心接口）
+- POST /v1/omni/streaming_voice — SSE 流式语音对话
+
+voice_chat 实现细节：
+1. 解码 audio_base64 → np.float32
+2. 保存临时 WAV 文件
+3. omni_init（按需）
+4. POST /prefill（传入 WAV 路径）
+5. POST /decode（stream=False，轮询输出目录）
+6. 合并所有 chunk_X/llm_text.txt → 完整文本
+7. 合并所有 wav_X.wav → 完整 WAV → base64
+8. 返回 {success, round, text, audio_base64}
+
+### 显存分析
+```
+阶段                     | 显存
+llama-server 纯文本      | ~5.7GB
++ vision mmproj          | ~6.7GB
++ KV cache (8192)        | ~7.9GB
++ compute buffers        | ~8.6GB
++ omni_init (audio+tts)  | ~9.6GB (+1GB, CPU offload)
++ runtime 动态           | ~10.9GB
+余量                     | ~5GB/16GB
+```
+
+### 关键教训
+1. **token2wav_device=cpu 是救命配置**：如果默认 GPU 加载，omni_init 直接 OOM（16GB 不够）→ 把 ~890MB 的 token2wav 放 CPU
+2. **每次重启 llama-server 后要重新 omni_init**：omni 状态不持久化
+3. **decode 要等够时间**：合成 TTS 可能需 30-120s，timeout 设 300s
+4. **reset 在 decode 卡死后可能超时**：kill 进程比等 reset 快
+5. **llama-server 接收 WAV 路径前缀而非 base64**：prefill 的 audio_path_prefix 是去掉扩展名的文件路径