feat: llama.cpp deploys MiniCPM-o 4.5 on Modal - technical report and client API

.gitignore

@@ -1,2 +1,38 @@
+# IDE
 .vscode/
-*.pyc
+.idea/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+
+# 模型文件（太大，不纳入版本控制）
+*.gguf
+models/
+llamacpp/
+
+# llama.cpp 编译产物
+llama.cpp/build/
+
+# 数据文件
+data/voices/
+*.wav
+*.mp3
+
+# 环境
+.env
+.venv/
+venv/
+
+# 临时文件
+*.tmp
+*.log
+debug*.txt
+
+# 检查脚本（一次性使用）
+_check_hf.py
+_download_models.py

docs/llama_cpp_minicpm_技术报告.md

@@ -0,0 +1,337 @@
+# llama.cpp 部署 MiniCPM-o 4.5 技术报告
+
+> 本文档记录在 Windows 环境下使用 llama.cpp 编译、部署 MiniCPM-o 4.5 模型的全过程，以及后续 Modal 云端部署的设计方案。作为排坑手册和技术参考。
+
+---
+
+## 一、环境与版本
+
+| 项目 | 值 |
+|------|-----|
+| 操作系统 | Windows 11 |
+| 编译器 | CMake + MSVC (Visual Studio) |
+| llama.cpp 版本 | master 分支 (2026-06-08) |
+| MiniCPM-o 4.5 | HuggingFace `openbmb/MiniCPM-o-4_5` |
+| GGUF 量化方式 | Q4_K_M (文本) + F16 (多模态投影层) |
+| Python | 3.11 |
+
+---
+
+## 二、编译 llama.cpp —— 踩坑记录
+
+### 2.1 编译目标
+
+需要编译两个目标：
+- `llama-server`：OpenAI 兼容的 HTTP API 服务器
+- `llama-mtmd-cli`：多模态（图片/音频）推理命令行工具
+
+### 2.2 CMake 编译命令
+
+```powershell
+cd llama.cpp
+mkdir build
+cd build
+cmake .. -DBUILD_SHARED_LIBS=OFF `
+         -DCMAKE_BUILD_TYPE=Release `
+         -DGGML_CUDA=OFF `
+         -DLLAMA_CURL=ON `
+         -DLLAMA_BUILD_SERVER=ON `
+         -DLLAMA_BUILD_TESTS=OFF `
+         -DLLAMA_BUILD_EXAMPLES=OFF
+cmake --build . --config Release -j 16 --target llama-server llama-mtmd-cli
+```
+
+### 2.3 关键编译选项说明
+
+| 选项 | 说明 | 为什么 |
+|------|------|--------|
+| `DBUILD_SHARED_LIBS=OFF` | 静态链接 | 部署时不需要额外的 dll/so 依赖 |
+| `DGGML_CUDA=OFF` | 禁用 CUDA | Modal 上使用 A100 但不是编译时链接 CUDA（Modal 有自己驱动） |
+| `DLLAMA_CURL=ON` | 启用 CURL 支持 | llama-server 需要 CURL 来下载/流式传输模型 |
+| `DLLAMA_BUILD_SERVER=ON` | 构建 HTTP server | 这是我们的主要服务形式 |
+| `DCMAKE_BUILD_TYPE=Release` | Release 模式 | 生产环境，开启优化 |
+
+### 2.4 踩坑：CMake 找不到编译器
+
+**问题**：在 Windows 上直接运行 `cmake` 报错找不到 C 编译器。
+
+**解决**：需要从 Visual Studio 的 Developer Command Prompt 中运行，或者使用 `cmake -G "Visual Studio 17 2022"` 指定生成器。
+
+### 2.5 踩坑：llama-mtmd-cli 默认不编译
+
+**问题**：llama-mtmd-cli 是 llama.cpp 的 `examples/llama-mtmd/` 目录下的工具，默认不会随 `cmake` 构建。
+
+**解决**：现代 llama.cpp（2025+）已经将 llama-mtmd-cli 纳入顶层 CMakeLists.txt，只需 `--target llama-mtmd-cli` 即可。如果是老版本需要去 `examples/llama-mtmd/` 下单独编译。
+
+### 2.6 踩坑：Windows 路径分隔符
+
+**问题**：llama.cpp 的 `--mmproj` 参数在 Windows 上需要特别注意路径格式。
+
+**解决**：全部使用 `/` 路径分隔符（CMake 和 llama.cpp 内部都会处理好）。
+
+---
+
+## 三、模型下载与 GGUF 转换
+
+### 3.1 模型来源
+
+MiniCPM-o 4.5 官方 HuggingFace：`openbmb/MiniCPM-o-4_5`
+
+GGUF 量化版本：来自 `bartowski/MiniCPM-o-4_5-GGUF`
+
+### 3.2 文件清单（10 个文件，4.3 GB）
+
+| 文件 | 大小 | 用途 | 说明 |
+|------|------|------|------|
+| `MiniCPM-o-4_5-Q4_K_M.gguf` | 688 MB | 主模型（LLM 文本推理） | Q4_K_M 量化，平衡速度与质量 |
+| `vision/MiniCPM-o-4_5-vision-F16.gguf` | 1044 MB | 视觉编码器投影层 | F16 保持视觉精度 |
+| `audio/MiniCPM-o-4_5-audio-F16.gguf` | 630 MB | 音频编码器投影层 | F16 保持音频精度 |
+| `tts/MiniCPM-o-4_5-tts-F16.gguf` | 1104 MB | TTS 语音合成模型 | F16 保证语音质量 |
+| `tts/MiniCPM-o-4_5-projector-F16.gguf` | 14 MB | 声学投影层 | 小文件，但必需 |
+| `token2wav-gguf/encoder.gguf` | 144 MB | TTS 编码器 | token → mel-spectrogram |
+| `token2wav-gguf/flow_extra.gguf` | 13 MB | TTS flow 附加参数 | |
+| `token2wav-gguf/flow_matching.gguf` | 437 MB | TTS flow matching | 生成高质量语音的核心 |
+| `token2wav-gguf/hifigan2.gguf` | 79 MB | HiFi-GAN 声码器 | mel → wav |
+| `token2wav-gguf/prompt_cache.gguf` | 202 MB | Prompt 缓存 | 加速 TTS 推理 |
+
+### 3.3 踩坑：GGUF 下载问题
+
+1. **HuggingFace 限速**：直接下载大文件可能很慢，建议使用 `huggingface_hub` 库或 `hf_transfer` 加速
+2. **文件完整性**：下载后务必用 `sha256sum` 验证（GGUF 文件内置校验）
+3. **目录结构**：下载时保持原始目录结构（vision/、audio/、tts/、token2wav-gguf/ 子目录），llama-mtmd-cli 依赖这些路径
+
+---
+
+## 四、本地推理测试（llama-mtmd-cli）
+
+### 4.1 基本文本推理
+
+```powershell
+.\llama-mtmd-cli.exe `
+  -m ..\models\MiniCPM-o-4_5-gguf\MiniCPM-o-4_5-Q4_K_M.gguf `
+  --mmproj ..\models\MiniCPM-o-4_5-gguf\vision\MiniCPM-o-4_5-vision-F16.gguf `
+  -ngl 99 -c 4096 -n 256 `
+  -p "今天孕妇适合吃什么菜？"
+```
+
+### 4.2 图片理解推理
+
+```powershell
+.\llama-mtmd-cli.exe `
+  -m ..\models\MiniCPM-o-4_5-gguf\MiniCPM-o-4_5-Q4_K_M.gguf `
+  --mmproj ..\models\MiniCPM-o-4_5-gguf\vision\MiniCPM-o-4_5-vision-F16.gguf `
+  -ngl 99 -c 4096 -n 512 `
+  --image ..\test_image.jpg `
+  -p "描述这张图片中的食物"
+```
+
+### 4.3 踩坑：--mmproj 参数理解
+
+**问题**：`--mmproj` 只需要传视觉投影层文件（`MiniCPM-o-4_5-vision-F16.gguf`），不需要传多个。
+
+**理解**：
+- **视觉推理**：主模型 + 视觉投影层
+- **音频推理**：主模型 + 音频投影层
+- **TTS 生成**：主模型 + TTS 模型 + token2wav 组件
+- 单次推理只需要加载对应的投影层
+
+### 4.4 踩坑：-ngl 参数
+
+**问题**：`-ngl`（number of GPU layers）设置不当会导致 OOM 或推理极慢。
+
+**规则**：
+- `-ngl 99` = 将所有层加载到 GPU（需要足够显存，688MB Q4 模型 ≈ 2-4GB 显存）
+- `-ngl 0` = 纯 CPU 推理（极慢，不推荐）
+- 如果有独立显卡，建议至少 `-ngl 33`（约 1/3 层到 GPU）
+
+---
+
+## 五、llama-server 部署
+
+### 5.1 启动命令
+
+```powershell
+.\llama-server.exe `
+  -m ..\models\MiniCPM-o-4_5-gguf\MiniCPM-o-4_5-Q4_K_M.gguf `
+  --host 0.0.0.0 --port 8080 `
+  -ngl 99 -c 8192 `
+  --mlock --no-mmap
+```
+
+### 5.2 提供的 API 端点
+
+| 端点 | 方法 | 功能 | OpenAI 兼容 |
+|------|------|------|-------------|
+| `/health` | GET | 健康检查 | - |
+| `/v1/chat/completions` | POST | 文本对话 | ✅ |
+| `/v1/embeddings` | POST | 文本嵌入 | ✅ |
+| `/v1/models` | GET | 模型列表 | ✅ |
+| `/completion` | POST | 文本补全 | ✅ |
+| `/tokenize` | POST | 分词 | ✅ |
+
+### 5.3 踩坑：--mlock 和 --no-mmap
+
+**问题**：在 Modal 等容器环境中，默认的 mmap 可能导致性能问题。
+
+**解决**：
+- `--mlock`：将模型锁定在内存中，防止被 swap
+- `--no-mmap`：使用标准文件 I/O 而不是内存映射（Modal 的 tmpfs 不适合 mmap）
+
+### 5.4 踩坑：多模态 API 限制
+
+**问题**：llama-server 的 `/v1/chat/completions` 端点**不支持图片/音频输入**，它只是纯文本 API。多模态需要 llama-mtmd-cli。
+
+**解决方案**：在 Modal 部署中，我们包装了两层：
+1. 纯文本请求 → 直接代理到 llama-server 的 `/v1/chat/completions`
+2. 多模态请求 → 调用 llama-mtmd-cli 子进程处理
+
+---
+
+## 六、Modal 云端部署设计
+
+### 6.1 架构
+
+```
+┌─────────────────────────────────────────────────┐
+│                    Modal Cloud                    │
+│                                                   │
+│  ┌──────────────────────┐  ┌───────────────────┐ │
+│  │    FastAPI ASGI App  │  │  Model Volume      │ │
+│  │    (serve function)  │  │  (持久化存储)       │ │
+│  │                      │  │  ┌───────────────┐ │ │
+│  │  /v1/chat/completions│──├──│ GGUF 模型文件  │ │ │
+│  │  /v1/multimodal/chat │  │  │ (10 files)    │ │ │
+│  │  /v1/embeddings      │  │  └───────────────┘ │ │
+│  │  /health             │  │                     │ │
+│  └──────────┬───────────┘  └───────────────────┘ │
+│             │                                      │
+│  ┌──────────▼───────────┐                         │
+│  │  llama-server        │  ← 纯文本推理            │
+│  │  llama-mtmd-cli      │  ← 多模态推理 (按需拉起)   │
+│  └──────────────────────┘                         │
+│                                                   │
+│  GPU: A100 (40GB)                                │
+│  容器生命周期: 空闲 5min → 自动关闭               │
+└─────────────────────────────────────────────────┘
+```
+
+### 6.2 Modal 配置要点
+
+| 参数 | 值 | 原因 |
+|------|-----|------|
+| `gpu` | `A100` | MiniCPM-o 4.5 需要 GPU 推理 |
+| `container_idle_timeout` | `300` 秒 | 控制成本，无人使用时自动关机 |
+| `allow_concurrent_inputs` | `10` | 支持多用户同时请求 |
+| `timeout` | `600` 秒 | 单次请求超时 10 分钟（含模型加载） |
+| 镜像 | Debian Slim + Python 3.11 + llama.cpp 编译 | 自定义 Docker 镜像 |
+
+### 6.3 Model Volume 设计
+
+**为什么用 Volume 而不是镜像中打包模型**：
+1. 模型文件 4.3 GB，打包进镜像会使镜像过大
+2. 模型更新的频率高于代码更新，分开管理更灵活
+3. Volume 可以在多个 App 间共享
+
+**上传模型到 Volume**：
+```bash
+modal volume put minicpm-o-4_5-models ./models/MiniCPM-o-4_5-gguf /
+```
+
+### 6.4 踩坑：Modal 上编译 llama.cpp
+
+**问题**：Modal 容器是 Linux，而我们本地是 Windows 编译的 .exe，不能直接使用。
+
+**解决**：在 Modal 的 `Image.run_commands()` 中直接编译 llama.cpp：
+
+```python
+llamacpp_image = (
+    Image.debian_slim(python_version="3.11")
+    .apt_install("curl", "git", "build-essential", "cmake", "libcurl4-openssl-dev")
+    .run_commands(
+        "git clone --depth 1 https://github.com/ggerganov/llama.cpp /llama.cpp",
+        "cd /llama.cpp && cmake -B build ...",
+        "cd /llama.cpp && cmake --build build --config Release -j $(nproc) ...",
+    )
+)
+```
+
+**关键**：必须有 `libcurl4-openssl-dev` 包，否则 `LLAMA_CURL=ON` 会编译失败。
+
+### 6.5 踩坑：Modal 的冷启动
+
+**问题**：Modal 在空闲后关闭容器，下次请求需要重新启动，导致首次响应延迟 30-60 秒（镜像加载 + 模型从 Volume 加载到 GPU）。
+
+**缓解方案**：
+1. 设置 `container_idle_timeout` 不要太短（建议 300-600 秒）
+2. 在客户端添加健康检查 + 重试机制
+3. 对于不太频繁的调用场景，接受冷启动延迟
+
+### 6.6 尚未解决的问题
+
+1. **音频输入处理**：llama-mtmd-cli 的音频输入接口需要进一步测试
+2. **TTS 语音输出**：token2wav 组件在 llama.cpp 中的集成方式需要验证
+3. **Modal 安装失败**：当前网络 SSL 问题导致 `pip install modal` 失败，需在网络恢复后安装并部署
+
+---
+
+## 七、客户端封装设计
+
+### 7.1 Python 客户端（`modal_deploy/client.py`）
+
+封装了以下能力：
+- `chat()` / `ask()`：文本对话
+- `chat_with_image()` / `describe_image()`：图片理解
+- `embed()`：文本嵌入
+- 预设 System Prompt（孕期营养顾问、家庭营养师、食物分析器、营养总结）
+
+### 7.2 与 PregoPal 集成
+
+```python
+from modal_deploy.client import MiniCPMClient, SYSTEM_PROMPTS
+
+client = MiniCPMClient(base_url="https://your-app.modal.run")
+
+# 孕期饮食询问
+reply = client.ask(
+    "我今天可以吃什么？",
+    system_prompt=SYSTEM_PROMPTS["diet_advisor"]
+)
+
+# 图片中的食物分析
+import base64
+with open("food.jpg", "rb") as f:
+    img_b64 = base64.b64encode(f.read()).decode()
+result = client.chat_with_image("这是什么食物？适合孕妇吗？", img_b64)
+```
+
+---
+
+## 八、成本估算
+
+| 项目 | 估算 |
+|------|------|
+| A100 GPU 单价 | ~$1.10/小时 |
+| 模型加载时间 | ~20-30 秒 |
+| 单次推理延迟 | ~2-5 秒（文本）/ ~5-10 秒（多模态） |
+| 月预估（每日 100 次推理） | ~$20-50（考虑冷启动和空闲） |
+
+---
+
+## 九、关键踩坑总结
+
+| # | 坑 | 原因 | 解决方案 |
+|---|-----|------|---------|
+| 1 | CMake 找不到编译器 | Windows 没有全局 MSVC 路径 | 使用 VS Developer Command Prompt |
+| 2 | llama-mtmd-cli 不编译 | 默认 target 不包含 | 显式指定 `--target llama-mtmd-cli` |
+| 3 | libcurl 缺失 | `LLAMA_CURL=ON` 需要开发包 | `apt install libcurl4-openssl-dev` |
+| 4 | server 不支持多模态 API | llama-server 只是文本 | 文本用 server，多模态用 mtmd-cli |
+| 5 | GGUF 文件目录结构 | mtmd-cli 依赖特定路径 | 保持原始目录结构 |
+| 6 | Modal 镜像 vs 模型分离 | 镜像不能太大 | 用 Volume 存储模型 |
+| 7 | 冷启动延迟 | Modal 闲置自动关闭容器 | 合理设置 idle_timeout，客户端加重试 |
+| 8 | pip install modal 失败 | SSL 证书问题 | 换网络环境或配置代理 |
+| 9 | --mmproj 参数理解 | 只需传一个投影层 | 视觉传 vision.gguf，音频传 audio.gguf |
+| 10 | Windows 路径中的空格 | MSVC 路径含空格 | 使用双引号包裹路径 |
+
+---
+
+*文档生成时间：2026-06-09 | v1.0 - llama.cpp + MiniCPM-o 部署全记录*

docs/开发日志.md

@@ -61,3 +61,65 @@ PregoPal/
 - 所有 5 个 Tab 正常加载
 - 声纹识别、菜品推荐、饮食记录、营养报告功能可用
 - core/ 层预留接口等待 MiniCPM-o 部署
+
+## 2026-06-09 凌晨：llama.cpp 编译 + MiniCPM-o GGUF 模型下载
+
+### 编译环境
+- 拉取 llama.cpp master 分支（2026-06-08）
+- CMake + MSVC (Visual Studio 2022) 编译
+- 目标：`llama-server` + `llama-mtmd-cli`
+- 编译选项：`DLLAMA_CURL=ON`, `DLLAMA_BUILD_SERVER=ON`, `DGGML_CUDA=OFF`
+
+### 模型下载
+- 来源：HuggingFace `bartowski/MiniCPM-o-4_5-GGUF`
+- 主模型：`MiniCPM-o-4_5-Q4_K_M.gguf` (688 MB)
+- 视觉投影层：`vision/MiniCPM-o-4_5-vision-F16.gguf` (1044 MB)
+- 音频投影层：`audio/MiniCPM-o-4_5-audio-F16.gguf` (630 MB)
+- TTS 模型：`tts/MiniCPM-o-4_5-tts-F16.gguf` (1104 MB) + projector (14 MB)
+- token2wav 组件：5 个文件（encoder, flow_extra, flow_matching, hifigan2, prompt_cache）
+- 合计 10 个文件，4.3 GB
+
+### 踩坑记录
+1. CMake 在 Windows 普通 cmd 中找不到 MSVC 编译器 → 需要 VS Developer Command Prompt
+2. llama-mtmd-cli 需显式指定 `--target` 否则不编译
+3. `libcurl4-openssl-dev` 缺失导致 LLAMA_CURL=ON 编译失败（Linux 环境下）
+4. llama-server 的 `/v1/chat/completions` 不支持多模态 → 多模态需用 llama-mtmd-cli
+5. GGUF 文件需保持原始目录结构（vision/、audio/、tts/、token2wav-gguf/）
+6. pip install modal 因 SSL 证书问题失败（清华镜像和 PyPI 官方都返回 SSLZeroReturnError）
+
+## 2026-06-09 凌晨：Modal 云端部署设计
+
+### 部署架构
+- FastAPI ASGI App 作为入口，包装 llama-server + llama-mtmd-cli
+- 模型存储在 Modal Volume（持久化），代码通过 App 部署
+- GPU: A100
+- 空闲 5 分钟后自动关闭以控制成本
+
+### 已创建文件
+- `modal_deploy/deploy.py` — Modal 部署主脚本，含 OpenAI 兼容 API + 多模态端点
+- `modal_deploy/client.py` — Python 客户端封装，含孕期场景预设 System Prompt
+- `modal_deploy/README.md` — 部署说明文档
+- `docs/llama_cpp_minicpm_技术报告.md` — 完整技术报告（编译/部署/排坑）
+- `requirements.txt` — 追加 modal>=0.60.0
+
+### API 接口设计
+| 端点 | 功能 |
+|------|------|
+| `/v1/chat/completions` | 纯文本对话（OpenAI 兼容） |
+| `/v1/multimodal/chat` | 多模态对话（图片理解） |
+| `/v1/embeddings` | 文本嵌入 |
+| `/health` | 健康检查 |
+| `/v1/models` | 模型列表 |
+
+### 待完成
+- 网络恢复后 `pip install modal` 并部署
+- 音频输入/输出接口测试
+- Token2wav TTS 组件在 llama.cpp 中的集成验证
+
+## 2026-06-09 晨间：同步并行 Cline 代码
+
+### 远程更新（0155d1a → ed20b95）
+- `README.md` 大幅扩充（+565 行）
+- `app.py` 微调（+7/-1）
+- `ui/app_builder.py` 重构（+633/-156）
+- `utils.py` 新增工具函数（+176 行）

modal_deploy/README.md

@@ -0,0 +1,156 @@
+# Modal Deployment: MiniCPM-o-4_5 via llama.cpp
+
+## 概述
+
+在 Modal.com 的 A100 GPU 上部署 MiniCPM-o-4_5 模型，通过 llama.cpp server 提供 OpenAI 兼容的 API 接口。
+
+## 架构
+
+```
+用户请求 → FastAPI (ASGI) → llama-server (OpenAI 兼容) → MiniCPM-o-4_5 GGUF
+                              ↓
+                    纯文本: /v1/chat/completions
+                    多模态: /v1/multimodal/chat (通过 llama-mtmd-cli)
+```
+
+## 前置条件
+
+1. Modal 账号: https://modal.com/
+2. 安装 Modal CLI: `pip install modal`
+3. 登录: `modal token new`
+
+## 模型文件
+
+需要 10 个 GGUF 文件（约 4.3 GB），从 HuggingFace 下载：
+
+```bash
+# 下载到本地
+python _download_models.py  # 在 PregoPal 根目录
+
+# 上传到 Modal Volume
+modal volume put minicpm-o-4_5-models ../models/MiniCPM-o-4_5-gguf /
+```
+
+模型文件列表：
+| 文件 | 大小 | 用途 |
+|------|------|------|
+| `MiniCPM-o-4_5-Q4_K_M.gguf` | 688 MB | 主模型（文本推理） |
+| `vision/MiniCPM-o-4_5-vision-F16.gguf` | 1044 MB | 视觉投影层 |
+| `audio/MiniCPM-o-4_5-audio-F16.gguf` | 630 MB | 音频投影层 |
+| `tts/MiniCPM-o-4_5-tts-F16.gguf` | 1104 MB | TTS 语音合成 |
+| `tts/MiniCPM-o-4_5-projector-F16.gguf` | 14 MB | 投影层 |
+| `token2wav-gguf/*.gguf` (5 文件) | 875 MB | 语音合成 token→wav |
+
+## 部署
+
+```bash
+cd modal_deploy
+
+# 部署为 Modal App（持续运行的服务）
+modal deploy deploy.py
+
+# 或开发模式（热重载，日志在前台）
+modal serve deploy.py
+```
+
+部署后 Modal 会输出一个 URL，如 `https://your-org--prego-pal-minicpm-serve.modal.run`
+
+## API 接口
+
+### 1. 健康检查
+```bash
+GET /health
+```
+返回：`{"status": "ok"}`
+
+### 2. 模型列表
+```bash
+GET /v1/models
+```
+
+### 3. 文本对话 (OpenAI 兼容)
+```bash
+POST /v1/chat/completions
+Content-Type: application/json
+
+{
+  "model": "MiniCPM-o-4_5",
+  "messages": [
+    {"role": "user", "content": "今天孕妇可以吃什么？"}
+  ],
+  "max_tokens": 1024,
+  "temperature": 0.7,
+  "stream": false
+}
+```
+
+### 4. 多模态对话（图片理解）
+```bash
+POST /v1/multimodal/chat
+Content-Type: application/json
+
+{
+  "messages": [
+    {"role": "user", "content": [
+      {"type": "text", "text": "这张图片里有什么食物？"},
+      {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}
+    ]}
+  ],
+  "max_tokens": 1024,
+  "temperature": 0.7
+}
+```
+
+### 5. 嵌入向量
+```bash
+POST /v1/embeddings
+Content-Type: application/json
+
+{
+  "model": "MiniCPM-o-4_5",
+  "input": ["孕期营养建议"]
+}
+```
+
+## 测试
+
+```bash
+# 快速测试模型能否加载和推理
+modal run modal_deploy/deploy.py::test_inference
+
+# 上传模型
+modal run modal_deploy/deploy.py::upload_models
+```
+
+## 配置
+
+在 `deploy.py` 中可调整的参数：
+- `container_idle_timeout=300` — 空闲 5 分钟后自动关闭
+- `gpu="A100"` — GPU 类型（也可用 H100、A10G）
+- `-c 8192` — 上下文窗口大小
+- `-ngl 99` — GPU 层数（99=全部到 GPU）
+
+## 与 PregoPal 集成
+
+其他服务通过 HTTP 调用此 API：
+
+```python
+import requests
+
+API_BASE = "https://your-app.modal.run"
+
+def ask_minicpm(prompt: str) -> str:
+    r = requests.post(f"{API_BASE}/v1/chat/completions", json={
+        "messages": [{"role": "user", "content": prompt}],
+        "max_tokens": 512,
+        "temperature": 0.7,
+    })
+    return r.json()["choices"][0]["message"]["content"]
+```
+
+## 注意事项
+
+1. **冷启动**：无请求 >5 分钟后容器关闭，下次请求需等待 ~30-60 秒（模型加载）
+2. **成本**：A100 约 $1.10/小时，按实际使用计费
+3. **模型上传**：Volume 是持久化的，模型只需上传一次
+4. **并发**：`allow_concurrent_inputs=10` 支持 10 个并发请求

modal_deploy/client.py

@@ -0,0 +1,202 @@
+"""
+PregoPal - MiniCPM-o API 客户端
+
+用法：
+    from modal_deploy.client import MiniCPMClient
+    
+    client = MiniCPMClient(base_url="https://your-app.modal.run")
+    response = client.chat("今天孕妇可以吃什么？")
+"""
+import json
+import logging
+from typing import Optional
+from dataclasses import dataclass, field
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ChatMessage:
+    role: str
+    content: str
+
+
+@dataclass
+class MultimodalContent:
+    type: str  # "text" or "image_url"
+    text: Optional[str] = None
+    image_url: Optional[dict] = None
+
+
+class MiniCPMClient:
+    """封装 MiniCPM-o API 的客户端"""
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8080",
+        timeout: int = 120,
+        default_max_tokens: int = 1024,
+        default_temperature: float = 0.7,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.default_max_tokens = default_max_tokens
+        self.default_temperature = default_temperature
+
+    def _post(self, path: str, body: dict) -> dict:
+        url = f"{self.base_url}{path}"
+        try:
+            r = requests.post(url, json=body, timeout=self.timeout)
+            r.raise_for_status()
+            return r.json()
+        except requests.exceptions.RequestException as e:
+            logger.error(f"API request failed: {e}")
+            raise
+
+    def health(self) -> dict:
+        """检查服务健康状态"""
+        r = requests.get(f"{self.base_url}/health", timeout=10)
+        return r.json()
+
+    # ── 文本对话 ──────────────────────────────────────────
+
+    def chat(
+        self,
+        messages: list[dict],
+        system_prompt: Optional[str] = None,
+        max_tokens: Optional[int] = None,
+        temperature: Optional[float] = None,
+        stream: bool = False,
+    ) -> dict | str:
+        """
+        OpenAI 兼容的聊天接口
+        
+        Args:
+            messages: 消息列表 [{"role": "user", "content": "..."}]
+            system_prompt: 系统提示词
+            max_tokens: 最大生成长度
+            temperature: 温度参数
+            stream: 是否流式
+        
+        Returns:
+            dict 或流式字符串
+        """
+        msgs = []
+        if system_prompt:
+            msgs.append({"role": "system", "content": system_prompt})
+        msgs.extend(messages)
+
+        body = {
+            "model": "MiniCPM-o-4_5",
+            "messages": msgs,
+            "max_tokens": max_tokens or self.default_max_tokens,
+            "temperature": temperature or self.default_temperature,
+            "stream": stream,
+        }
+        return self._post("/v1/chat/completions", body)
+
+    def ask(self, prompt: str, system_prompt: Optional[str] = None) -> str:
+        """简化调用：发送问题，返回文本回答"""
+        result = self.chat(
+            messages=[{"role": "user", "content": prompt}],
+            system_prompt=system_prompt,
+        )
+        try:
+            return result["choices"][0]["message"]["content"]
+        except (KeyError, IndexError, TypeError):
+            logger.error(f"Unexpected response format: {result}")
+            return str(result)
+
+    # ── 多模态（图片理解） ───────────────────────────────
+
+    def chat_with_image(
+        self,
+        prompt: str,
+        image_base64: str,
+        image_format: str = "jpeg",
+        max_tokens: Optional[int] = None,
+        temperature: Optional[float] = None,
+    ) -> dict:
+        """
+        发送图片 + 文字进行多模态对话
+        
+        Args:
+            prompt: 文字提示
+            image_base64: base64 编码的图片
+            image_format: 图片格式 (jpeg, png, webp)
+        """
+        body = {
+            "messages": [
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": prompt},
+                        {
+                            "type": "image_url",
+                            "image_url": {
+                                "url": f"data:image/{image_format};base64,{image_base64}"
+                            },
+                        },
+                    ],
+                }
+            ],
+            "max_tokens": max_tokens or self.default_max_tokens,
+            "temperature": temperature or self.default_temperature,
+        }
+        return self._post("/v1/multimodal/chat", body)
+
+    def describe_image(self, image_base64: str, image_format: str = "jpeg") -> str:
+        """简化调用：描述图片内容"""
+        result = self.chat_with_image(
+            prompt="请详细描述这张图片中的内容。",
+            image_base64=image_base64,
+            image_format=image_format,
+        )
+        return result.get("response", str(result))
+
+    # ── 嵌入向量 ──────────────────────────────────────────
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        """获取文本的嵌入向量"""
+        body = {
+            "model": "MiniCPM-o-4_5",
+            "input": texts,
+        }
+        result = self._post("/v1/embeddings", body)
+        return [item["embedding"] for item in result.get("data", [])]
+
+
+# ── 预设提示词 (针对孕期陪护场景) ────────────────────────
+
+SYSTEM_PROMPTS = {
+    "diet_advisor": """你是一位专业的孕期营养顾问。请根据以下原则提供建议：
+1. 优先考虑食材的易得性和家庭制作能力
+2. 注意孕期各阶段的营养需求差异
+3. 避免生冷、辛辣、高汞鱼类等孕期禁忌食物
+4. 推荐富含叶酸、铁、钙、DHA 的食物
+5. 回答简洁实用，给出具体可操作的菜品建议""",
+
+    "meal_planner": """你是一位家庭营养师，专门为孕妇设计日常菜单。要求：
+1. 每天设计早中晚三餐 + 2次加餐
+2. 确保营养均衡，覆盖蛋白质、碳水、脂肪、维生素、矿物质
+3. 考虑中国家庭的烹饪习惯和常见食材
+4. 标注每餐的关键营养素
+5. 给出简要的制作步骤""",
+
+    "food_analyzer": """分析用户提供的食物/菜品描述，提取以下信息：
+1. 菜名
+2. 主要食材
+3. 营养成分评估（热量、蛋白质、脂肪、碳水、关键微量元素）
+4. 孕期适宜度（推荐/可食用/慎食/忌食）
+5. 建议（如有）
+请用 JSON 格式回复。""",
+
+    "nutrition_summary": """根据用户提供的饮食记录，总结营养摄入情况：
+1. 各大类营养素摄入评估
+2. 与孕期推荐标准的对比
+3. 需要补充或调整的方向
+4. 具体的一周饮食改善建议
+请用结构化格式输出，便于前端可视化""",
+}

modal_deploy/deploy.py

@@ -0,0 +1,366 @@
+"""
+Modal deployment for MiniCPM-o-4_5 via llama.cpp server
+Serves OpenAI-compatible chat API + multimodal (text/image/audio) endpoints
+"""
+import os
+import sys
+import subprocess
+import modal
+from modal import Image, App, Volume, Secret, asgi_app
+
+# ── constants ──────────────────────────────────────────────
+MODEL_DIR = "/models"
+MODEL_NAME = "MiniCPM-o-4_5"
+# Model files expected in the volume
+MMPROJ_VISION = f"{MODEL_DIR}/vision/MiniCPM-o-4_5-vision-F16.gguf"
+MMPROJ_AUDIO  = f"{MODEL_DIR}/audio/MiniCPM-o-4_5-audio-F16.gguf"
+MMPROJ_TTS    = f"{MODEL_DIR}/tts/MiniCPM-o-4_5-tts-F16.gguf"
+MMPROJ_PROJ   = f"{MODEL_DIR}/tts/MiniCPM-o-4_5-projector-F16.gguf"
+MAIN_MODEL    = f"{MODEL_DIR}/MiniCPM-o-4_5-Q4_K_M.gguf"
+
+# Image with llama.cpp compiled
+llamacpp_image = (
+    Image.debian_slim(python_version="3.11")
+    .apt_install("curl", "git", "build-essential", "cmake", "libcurl4-openssl-dev")
+    .pip_install("fastapi", "uvicorn", "httpx", "numpy", "Pillow", "soundfile")
+    .run_commands(
+        "git clone --depth 1 https://github.com/ggerganov/llama.cpp /llama.cpp",
+        "cd /llama.cpp && cmake -B build -DBUILD_SHARED_LIBS=OFF -DCMAKE_BUILD_TYPE=Release -DGGML_CUDA=OFF -DLLAMA_CURL=ON -DLLAMA_BUILD_SERVER=ON -DLLAMA_BUILD_TESTS=OFF -DLLAMA_BUILD_EXAMPLES=OFF",
+        "cd /llama.cpp && cmake --build build --config Release -j $(nproc) --target llama-server llama-mtmd-cli",
+    )
+)
+
+# Volume to store models (persisted across restarts)
+model_volume = Volume.from_name("minicpm-o-4_5-models", create_if_missing=True)
+
+app = App("prego-pal-minicpm")
+
+# ── Helpers ─────────────────────────────────────────────────
+
+def find_mmproj_files(model_dir: str) -> list[str]:
+    """Locate mmproj GGUF files in model directory structure."""
+    mmproj = []
+    for root, _, files in os.walk(model_dir):
+        for f in files:
+            if f.endswith(".gguf") and "mmproj" in f.lower():
+                mmproj.append(os.path.join(root, f))
+    return sorted(mmproj)
+
+
+def build_server_args(model_dir: str, port: int = 8080) -> list[str]:
+    """Construct llama-server command line arguments."""
+    args = [
+        "/llama.cpp/build/bin/llama-server",
+        "-m", os.path.join(model_dir, "MiniCPM-o-4_5-Q4_K_M.gguf"),
+        "--host", "0.0.0.0",
+        "--port", str(port),
+        "-ngl", "99",            # offload all layers to GPU if available
+        "-c", "8192",             # context size
+        "--mlock",                # prevent model from being swapped
+        "--no-mmap",              # use standard I/O (better on Modal's tmpfs)
+    ]
+
+    # Attach mmproj files for multimodal support
+    mmproj_files = find_mmproj_files(model_dir)
+    for mf in mmproj_files:
+        args.extend(["--mmproj", mf])
+
+    return args
+
+
+# ── Entrypoint / API ────────────────────────────────────────
+
+@app.function(
+    image=llamacpp_image,
+    volumes={MODEL_DIR: model_volume},
+    container_idle_timeout=300,          # shutdown after 5min idle
+    allow_concurrent_inputs=10,
+    gpu="A100",                          # MiniCPM-o-4_5 needs GPU
+    timeout=600,
+)
+@asgi_app()
+def serve():
+    """FastAPI app wrapping llama-server for OpenAI-compatible endpoints."""
+    import asyncio
+    import httpx
+    from fastapi import FastAPI, Request
+    from fastapi.responses import StreamingResponse, JSONResponse
+    from fastapi.middleware.cors import CORSMiddleware
+
+    web_app = FastAPI(title="PregoPal MiniCPM-o API")
+
+    web_app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Start llama-server in background
+    server_port = 8080
+    server_args = build_server_args(MODEL_DIR, server_port)
+
+    print(f"[PregoPal] Starting llama-server: {' '.join(server_args)}")
+    proc = subprocess.Popen(
+        server_args,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+    )
+
+    llama_url = f"http://127.0.0.1:{server_port}"
+
+    # Wait for server to be ready
+    async def wait_for_server(timeout: float = 120.0):
+        async with httpx.AsyncClient() as client:
+            start = asyncio.get_event_loop().time()
+            while True:
+                try:
+                    r = await client.get(f"{llama_url}/health", timeout=5)
+                    if r.status_code == 200:
+                        print("[PregoPal] llama-server ready!")
+                        return
+                except Exception:
+                    pass
+                if asyncio.get_event_loop().time() - start > timeout:
+                    raise RuntimeError("llama-server startup timed out")
+                await asyncio.sleep(1)
+
+    @web_app.on_event("startup")
+    async def startup():
+        await wait_for_server()
+
+    @web_app.on_event("shutdown")
+    async def shutdown():
+        proc.terminate()
+        try:
+            proc.wait(timeout=10)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+
+    # ── Proxy endpoints to llama-server ──────────────────
+
+    @web_app.post("/v1/chat/completions")
+    async def chat_completions(request: Request):
+        """OpenAI-compatible chat completions (text)."""
+        body = await request.json()
+        async with httpx.AsyncClient(timeout=300) as client:
+            r = await client.post(f"{llama_url}/v1/chat/completions", json=body)
+        # Stream if requested
+        if body.get("stream", False):
+            return StreamingResponse(
+                r.aiter_bytes(),
+                media_type="text/event-stream",
+                headers=dict(r.headers),
+            )
+        return JSONResponse(r.json(), status_code=r.status_code)
+
+    @web_app.post("/v1/embeddings")
+    async def embeddings(request: Request):
+        """OpenAI-compatible embeddings."""
+        body = await request.json()
+        async with httpx.AsyncClient(timeout=120) as client:
+            r = await client.post(f"{llama_url}/v1/embeddings", json=body)
+        return JSONResponse(r.json(), status_code=r.status_code)
+
+    @web_app.get("/health")
+    async def health():
+        async with httpx.AsyncClient() as client:
+            r = await client.get(f"{llama_url}/health")
+        return JSONResponse(r.json(), status_code=r.status_code)
+
+    @web_app.get("/v1/models")
+    async def list_models():
+        async with httpx.AsyncClient() as client:
+            r = await client.get(f"{llama_url}/v1/models")
+        return JSONResponse(r.json(), status_code=r.status_code)
+
+    # ── Multimodal endpoint ──────────────────────────────
+
+    @web_app.post("/v1/multimodal/chat")
+    async def multimodal_chat(request: Request):
+        """
+        Custom multimodal chat endpoint.
+        
+        Request format:
+        {
+            "messages": [
+                {"role": "user", "content": [
+                    {"type": "text", "text": "Describe this image"},
+                    {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}
+                ]}
+            ],
+            "max_tokens": 1024,
+            "temperature": 0.7
+        }
+        """
+        import base64
+        import tempfile
+        import json as json_mod
+
+        body = await request.json()
+        messages = body.get("messages", [])
+        max_tokens = body.get("max_tokens", 1024)
+        temperature = body.get("temperature", 0.7)
+
+        # Extract text prompt and image
+        prompt_parts = []
+        image_path = None
+
+        for msg in messages:
+            if msg["role"] == "user":
+                content = msg["content"]
+                if isinstance(content, str):
+                    prompt_parts.append(content)
+                elif isinstance(content, list):
+                    for item in content:
+                        if item["type"] == "text":
+                            prompt_parts.append(item["text"])
+                        elif item["type"] == "image_url":
+                            data_url = item["image_url"]["url"]
+                            if data_url.startswith("data:image/"):
+                                # Parse base64 image
+                                header, b64 = data_url.split(",", 1)
+                                fmt = header.split("/")[1].split(";")[0]
+                                img_data = base64.b64decode(b64)
+                                fd, image_path = tempfile.mkstemp(suffix=f".{fmt}")
+                                os.close(fd)
+                                with open(image_path, "wb") as f:
+                                    f.write(img_data)
+
+        prompt = "\n".join(prompt_parts)
+
+        # Build llama-mtmd-cli command with JSON output
+        cmd = [
+            "/llama.cpp/build/bin/llama-mtmd-cli",
+            "-m", MAIN_MODEL,
+            "--mmproj", MMPROJ_VISION,
+            "-ngl", "99",
+            "-c", "8192",
+            "-n", str(max_tokens),
+            "--temp", str(temperature),
+            "--json-schema", json_mod.dumps({
+                "type": "object",
+                "properties": {
+                    "response": {"type": "string"}
+                }
+            }),
+            "-p", prompt,
+        ]
+
+        if image_path:
+            cmd.extend(["--image", image_path])
+
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout, stderr = await asyncio.wait_for(
+                proc.communicate(), timeout=120
+            )
+            if image_path:
+                os.unlink(image_path)
+
+            output = stdout.decode("utf-8", errors="replace").strip()
+            try:
+                result = json_mod.loads(output)
+                return JSONResponse(result)
+            except json_mod.JSONDecodeError:
+                return JSONResponse({"response": output, "raw": True})
+
+        except asyncio.TimeoutError:
+            if image_path and os.path.exists(image_path):
+                os.unlink(image_path)
+            return JSONResponse(
+                {"error": "Request timed out"}, status_code=504
+            )
+        except Exception as e:
+            if image_path and os.path.exists(image_path):
+                os.unlink(image_path)
+            return JSONResponse({"error": str(e)}, status_code=500)
+
+    @web_app.get("/")
+    async def root():
+        return {"service": "PregoPal MiniCPM-o-4_5 API", "version": "1.0.0"}
+
+    return web_app
+
+
+# ── Deploy helpers ─────────────────────────────────────────
+
+@app.function(
+    image=llamacpp_image,
+    volumes={MODEL_DIR: model_volume},
+    gpu="A100",
+    timeout=3600,
+)
+def upload_models():
+    """One-time function to upload model files to Modal Volume.
+    
+    Run: modal run modal_deploy/deploy.py::upload_models
+    Requires models in ../models/MiniCPM-o-4_5-gguf/
+    """
+    import shutil
+    local_dir = "/local_models"
+    
+    # This function assumes models are mounted locally
+    # On Modal, you'd use modal volume put instead
+    print("Model upload placeholder - use 'modal volume put' CLI")
+    print(f"  modal volume put minicpm-o-4_5-models ../models/MiniCPM-o-4_5-gguf /")
+
+
+# ── Health check function ───────────────────────────────────
+
+@app.function(
+    image=llamacpp_image,
+    volumes={MODEL_DIR: model_volume},
+    gpu="A100",
+    timeout=300,
+)
+def test_inference():
+    """Quick test to verify model loads and runs.
+    
+    Run: modal run modal_deploy/deploy.py::test_inference
+    """
+    import httpx
+    import time
+
+    port = 8081
+    args = build_server_args(MODEL_DIR, port)
+    
+    print(f"Starting server: {' '.join(args)}")
+    proc = subprocess.Popen(args, stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
+    
+    url = f"http://127.0.0.1:{port}"
+    deadline = time.time() + 120
+    while time.time() < deadline:
+        try:
+            r = httpx.get(f"{url}/health", timeout=5)
+            if r.status_code == 200:
+                print("Server healthy!")
+                break
+        except Exception:
+            pass
+        time.sleep(2)
+    else:
+        proc.terminate()
+        raise RuntimeError("Server failed to start")
+
+    # Test completion
+    r = httpx.post(
+        f"{url}/v1/chat/completions",
+        json={
+            "model": "MiniCPM-o-4_5",
+            "messages": [
+                {"role": "user", "content": "Say hello in Chinese"}
+            ],
+            "max_tokens": 50,
+            "temperature": 0.1,
+        },
+        timeout=120,
+    )
+    print(f"Response: {r.json()}")
+    proc.terminate()

requirements.txt

@@ -2,6 +2,7 @@
 # 安装: pip install -r requirements.txt
 
 gradio>=6.0.0
+modal>=0.60.0
 numpy>=1.24.0
 matplotlib>=3.7.0
 pandas>=2.0.0