docs: add technical report for codex handoff (2026-06-13)

docs/技术报告_2026-06-13.md

@@ -0,0 +1,225 @@
+# PregoPal — llama.cpp-omni 全双工部署技术报告
+
+> 作者: Qclaw | 日期: 2026-06-13 08:00 | 项目: PregoPal 黑客松
+
+---
+
+## 1. 项目架构
+
+```
+用户 (HTTP) → FastAPI (serve()) → llama-server (子进程, 端口 8081)
+                                  → llama-omni-server (子进程, 端口 8082, 含 omni 端点)
+```
+
+**部署方式:** Modal (T4 GPU, 16GB VRAM)
+**生产 URL:** https://andrew-jiabin--prego-pal-minicpm-omni-serve.modal.run
+**当前 Image:** `im-kINUqibAmbYIS6brxSIOIY` (建于 2026-06-12 23:42, 4737s)
+
+**工作状态:**
+- ✅ 文本推理 (chat/completions): 正常（中文 1.0s, 英文 1.9s）
+- ✅ TTS `/v1/audio/speech`: 通过 serve() 代理，需要再验证
+- ✅ STT `/v1/audio/transcriptions`: 同上
+- ❌ **全双工 omni (init → prefill → generate SSE): 失败**
+
+---
+
+## 2. 当前核心问题: omni_init 500
+
+### 2.1 症状
+
+```
+modal run -m modal_deploy.deploy_omni::test_omni
+→ llama-omni-server 启动正常（1s）
+→ llama-server 启动正常（7-11s）
+→ POST /v1/stream/omni_init 返回错误:
+  "Server disconnected without sending a response"
+```
+
+### 2.2 根因分析
+
+**`llama-omni-server` 是独立进**，不含预先加载的 LLM 模型。当 `omni_init` 被调用时：
+
+```cpp
+omni_init(&params, media_type, use_tts, tts_bin_dir, tts_gpu_layers,
+           token2wav_device, duplex_mode,
+           /*existing_model=*/nullptr,    // ← 没有已加载的模型
+           /*existing_ctx=*/nullptr,      // ← 没有已有的上下文
+           output_dir);
+```
+
+`omni_init` 内部调用 `common_context_params_to_llama()` 和 `llama_load_model_from_file()` 来重新加载 LLM 模型。但过程失败，`omni_init` 返回 `nullptr`，`server-omni.cpp` 的 handler 返回 500。
+
+### 2.3 已尝试的修复
+
+| # | 修复 | 结果 |
+|---|------|------|
+| 1 | 在 `server-omni.cpp` 中设置 `params.model.path`, `params.vpm_model`, `params.apm_model`, `params.tts_model` | 进程崩溃 (`Server disconnected`) |
+| 2 | 额外设置 `params.n_parallel=1, params.n_ctx=4096` 避免 `n_seq_max <= 256` 错误 | 进程仍崩溃 |
+| 3 | 通过 `git checkout` 恢复后发现修复被回滚 | 代码回到初始版 |
+| 4 | 实际 commit `6451051` 已包含了修复，但测试时用的旧 Image | 行为未变化 |
+
+### 2.4 可能的原因
+
+建议如下排查方向（从最可能到最不可能）：
+
+1. **模型路径不匹配**: `model_dir` 传的是 `/models/MiniCPM-o-4_5-gguf/`，但 `server-omni.cpp` 将 LLM 模型路径硬编码为 `model_dir + "/MiniCPM-o-4_5-Q4_K_M.gguf"` — 需要验证该文件是否存在（Volume `/models/MiniCPM-o-4_5-gguf/token2wav-gguf/` 下已有正确的文件）
+
+2. **`common_params` 字段名**: `params.model` 是 `common_params_model` 结构体，需要确保 `.path` 赋值正确。检查 `server-omni.cpp` 第 139-145 行是否格式正确。
+
+3. **GPU 内存不足**: `llama-server`（主 LLM）+ `llama-omni-server`（重新加载 LLM）同时运行时，T4 16GB 可能不够。建议先验证单一切片：在 `test_omni` 中只启动 `llama-omni-server`，不启动 `llama-server`。
+
+4. **`LLAMA_EXAMPLE_SERVER` 宏**: `omni.cpp` 内部可能有条件编译逻辑影响 context 创建；`server-omni.cpp` 是否定义了正确的宏？
+
+---
+
+## 3. 源码关键文件位置
+
+```
+C:\Users\Andre\codes\LJB\hackthon\for_qclaw\PregoPal\
+├── modal_deploy/
+│   ├── deploy_omni.py           # Modal 部署脚本（编译、serve、测试）
+│   ├── diagnoze_volume.py       # Volume 诊断
+│   ├── build_llama_server.sh    # 构建脚本
+│   └── llamacpp_omni/           # llama.cpp-omni 源码 (OpenBMB fork)
+│       └── tools/
+│           ├── server/
+│           │   ├── server.cpp       # llama-server (15KB, 无 omni 端点)
+│           │   ├── server-omni.cpp  # llama-omni-server (含 omni 端点, 关键文件)
+│           │   └── CMakeLists.txt
+│           └── omni/
+│               ├── omni.h           # omni_init() 声明
+│               └── omni.cpp         # omni_init() 实现 (约11000行)
+├── docs/
+│   ├── 开发日志.md                # 完整的开发历史
+│   ├── 技术报告_2026-06-11.md     # 跨天技术报告
+│   ├── README_modal_deploy.md     # 部署指南
+│   └── 云端部署经验.md            # 部署经验总结
+├── .git/                          # Git 仓库 (Hugging Face)
+└── tmp_*.py                       # 临时测试脚本（已删）
+```
+
+---
+
+## 4. Modal 容器环境
+
+### 4.1 预安装依赖
+
+Modal Image (`_omni_image`) 包含:
+- CUDA 12 + cuBLAS
+- CMake + GCC
+- Python 包: fastapi, httpx, numpy, soundfile, modal
+
+### 4.2 Volume 结构
+
+Volume `minicpm-o-4_5-models` 挂载到 `/models/`:
+```
+/models/
+└── MiniCPM-o-4_5-gguf/
+    ├── MiniCPM-o-4_5-Q4_K_M.gguf       (LLM, ~8GB)
+    ├── vision/
+    │   └── MiniCPM-o-4_5-vision-F16.gguf
+    ├── audio/
+    │   └── MiniCPM-o-4_5-audio-F16.gguf
+    ├── tts/
+    │   ├── MiniCPM-o-4_5-tts-F16.gguf
+    │   └── MiniCPM-o-4_5-projector-F16.gguf
+    └── token2wav-gguf/
+        ├── encoder.gguf
+        ├── flow_extra.gguf
+        ├── flow_matching.gguf
+        ├── hifigan2.gguf
+        └── prompt_cache.gguf
+```
+
+### 4.3 编译目标
+
+当前的 Image recipe 编译两个目标:
+- `--target llama-server` (18KB wrapper, ~77min 含 CUDA kernels)
+- `--target llama-omni-server` (261KB 独立二进制, 增量 ~2s)
+
+**建议**: 保留两个目标，因为它们各自有独立作用。
+
+---
+
+## 5. Git 提交历史
+
+```
+6451051 (HEAD -> main) refactor: deprecate llama-omni-server...
+e0c2f3a fix: set n_parallel=1, n_ctx=4096 before omni_init...
+4429886 test_omni: add stderr capture for omni-server when init fails
+22e5fff feat: add llama-omni-server support with full-duplex omni endpoints
+```
+
+注意 `6451051` 的提交实际上保留了 `llama-omni-server`（重构被回滚了），但本地文件经过了修改。
+
+**远程仓库:** https://huggingface.co/spaces/build-small-hackathon/PregoPal
+
+---
+
+## 6. 建议 Codex 推进路线
+
+### Step 1: 诊断 omni_init 崩溃
+在本地（C++ 环境）编译 `llama-omni-server`，用 `gdb` 或加日志跟踪 `omni_init` 中的失败点。最直接的方法是：
+- 在 `server-omni.cpp` 的 omni_init handler 中，在调用 `omni_init()` 前后加 `fprintf(stderr, ...)` 输出
+- 或者在 `omni.cpp` 的 `omni_init()` 函数开头加日志
+
+### Step 2: 修复 omni_init
+常见修复方向：
+- 确保 `common_params` 中所有路径正确（`params.model.path`, `params.mmproj.path`, `params.vpm_model` 等）
+- 检查 `params.n_parallel` 和 `params.n_ctx` 是否被 `omni_init` 内部覆盖
+- 尝试 `params.use_mmap = false`（与 `--no-mmap` 一致）
+
+### Step 3: 验证全双工流程
+修复后验证:
+```
+POST /v1/stream/omni_init  → 200 {success: true}
+POST /v1/stream/prefill    → 200 (audio/image prefill)
+POST /v1/stream/decode     → SSE (text + audio tokens)
+```
+
+### Step 4: 前端集成
+将前端的录音 → base64 PCM → HTTP POST 到 FastAPI → 代理到 llama-omni-server 的流程打通。
+
+---
+
+## 7. 环境说明
+
+### Windows 本机
+- 项目目录: `C:\Users\Andre\codes\LJB\hackthon\for_qclaw\PregoPal\`
+- Python: `C:\Users\Andre\miniconda3\python.exe` (环境: base)
+- Modal: 已认证，Key 已配置
+- 本机无法直接运行 `modal shell` (Windows 不支持)
+
+### Modal 容器内
+- CPU: 4 vCPU
+- GPU: Tesla T4 (16GB VRAM)
+- RAM: 16GB
+- OS: Linux (Modal 容器)
+- Python: 3.12 (Modal 默认)
+
+### 编译参数
+```
+-DGGML_CUDA=ON
+-DGGML_CUDA_NO_VMM=ON
+-DLLAMA_BUILD_SERVER=ON
+-DLLAMA_BUILD_TESTS=OFF
+-DLLAMA_BUILD_EXAMPLES=OFF
+-DLLAMA_CUDA_FORCE_MMQ=ON
+-DCMAKE_CUDA_ARCHITECTURES='75;89'
+-DCMAKE_BUILD_TYPE=Release
+```
+
+---
+
+## 8. 当前瓶颈总结
+
+| 模块 | 状态 | 难度 |
+|------|------|------|
+| llama-server 文本推理 | ✅ 通过 | — |
+| llama-omni-server 编译 | ✅ 通过 | — |
+| llama-omni-server omni_init | ❌ 崩溃 | 中等 |
+| omni_init → prefill → decode | ❌ 未验证 | 未知 |
+| 前端集成 (Gradio) | ❌ 未开始 | 简单 |
+| 全双工真实测试 | ❌ 未开始 | 未知 |
+
+**估计剩余工作量**: 3-5 天（含 debug + 集成 + 测试）