docs: 部署成功报告 + 清理神秘文件 c

c

@@ -1,502 +0,0 @@
-# 🌸 PregoPal 项目理解与技术架构（v4 - Loop 驱动 + 三文档操作）
-
-> 本文档已完成重构，每个小节末尾附有批注区，便于你边看边标注意见。
-
----
-
-## 一、一句话定位
-
-**一个基于每日生命周期 Loop 驱动的孕期陪护 AI 助手**：每天首次启动时自动总结昨日饮食、对比国家营养标准（DRIs/膳食指南/体重标准），生成今日简报注入对话上下文；白天与家庭成员（通过声纹区分）自然交互，实时记录饮食、推荐食谱；次日循环往复。
-
-> **批注：** ________
-
----
-
-## 二、三个营养文档的操作方法
-
-你已经下载到 `data/nutrition/raw/` 的三个文件，各自承担不同角色：
-
-| 文档 | 文件 | 用途 | PregoPal 的操作方式 |
-|------|------|------|-------------------|
-| **① 体重增长标准** | `妊娠期妇女体重增长推荐值标准.md` | 体重监测基准 | **主动询问体重** — 每天 Loop 中检查是否需要询问，对照 BMI 分类给出评价 |
-| **② 膳食指南** | `中国孕期妇女膳食指南2022图片转md版.md` | 食谱推荐基准 | **作为推荐食谱的约束基础** — 根据孕期阶段用宝塔推荐量生成模板 |
-| **③ DRIs** | `备孕&孕早中晚三期和哺乳期的所有膳食营养素参考摄入量.md` | 营养分析基准 | **Agent 定期思考** — 每天自动对比 RNI，分析不足，写入次日预设 |
-
-> **批注：** ________
-
-### 2.1 体重增长标准 → 主动询问体重
-
-**数据来源**：WS/T 801-2022 表1
-
-```
-每天早上 Loop 的 weight_check 插件：
-  ├→ 检查 data/logs/ 中是否有近期的体重记录
-  ├→ 若无记录或记录超过 7 天
-  │   └→ 在今日简报中标记「需询问体重」
-  │      （UI 弹出体重卡片，或语音询问：「今天称体重了吗？」）
-  └→ 若有记录
-       ├→ 计算当前孕周、孕前 BMI、当前总增长值
-       ├→ 对照标准表：
-
-       | 孕前 BMI 分类         | 总增长范围  | 每周增长(中+晚) |
-       |----------------------|------------|----------------|
-       | 低体重 BMI<18.5      | 11.0~16.0  | 0.46(0.37~0.56) |
-       | 正常 18.5≤BMI<24.0   | 8.0~14.0   | 0.37(0.26~0.48) |
-       | 超重 24.0≤BMI<28.0   | 7.0~11.0   | 0.30(0.22~0.37) |
-       | 肥胖 BMI≥28.0        | 5.0~9.0    | 0.22(0.15~0.30) |
-
-       ├→ 在范围内 → ✅ 鼓励「体重增长很好，继续保持！」
-       └→ 超出范围 → ⚠️ 提醒「增长偏快/偏慢，建议调整饮食/咨询医生」
-```
-
-> **批注：** ________
-
-### 2.2 膳食指南 → 食谱推荐基础
-
-**数据来源**：中国孕期妇女平衡膳食宝塔（备孕/孕中期/孕晚期/哺乳期）
-
-```
-推荐食谱时，AI 的约束条件：
-  ├→ 孕中期宝塔：
-  │   奶类 300-500g，鱼禽蛋肉类 150-200g，谷类 200-250g
-  │   蔬菜 400-500g，水果 200-300g，薯类 75g
-  │   大豆 20g，坚果 10g，油 25g，盐 5g
-  │
-  ├→ 孕晚期宝塔：
-  │   奶类 300-500g，鱼禽蛋肉类 175-225g，谷类 225-275g
-  │   蔬菜 400-500g，水果 200-350g，薯类 75g
-  │   大豆 20g，坚果 10g，油 25g，盐 5g
-  │
-  └→ 膳食指南六条核心建议（嵌入系统提示词）：
-      1. 调整孕前体重至正常范围
-      2. 常吃含铁食物，选用碘盐，补充叶酸和维生素D
-      3. 孕吐严重者少量多餐
-      4. 孕中晚期增加奶、鱼、禽、蛋、瘦肉
-      5. 经常户外活动，禁烟酒
-      6. 愉快孕育新生命，积极准备母乳喂养
-```
-
-**原有 MEAL_TEMPLATES 的改造**：不再硬编码模板字符串，而是将上述宝塔约束条作为结构化 JSON 传递给 AI（或作为本地 fallback 兜底），由 AI 根据宝塔约束 + 用户偏好生成个性化食谱。
-
-> **批注：** ________
-
-### 2.3 DRIs → Agent 定期分析（自动运行 → 写入次日预设）
-
-**数据来源**：表15（孕早期）/ 表16（孕中期）/ 表17（孕晚期）/ 表18（哺乳期）
-
-```
-每天 Loop 的 dri_analysis 插件：
-  ├→ 读取昨日饮食记录（data/logs/饮食日志_YYYY-MM-DD.md）
-  ├→ 根据当前孕期阶段选择对应 DRIs 表
-  ├→ 关键营养素逐项对比（重点标记 RNI 与摄入量差异）：
-
-      ┌─────────────────────────────────────────────┐
-      │  营养素         RNI(孕中期)   昨日摄入   差异  │
-      ├─────────────────────────────────────────────┤
-      │  能量(MJ)       9.84(PAL II)  8.2       -17% │
-      │  蛋白质(g)      70           55         -21% │
-      │  钙(mg)         800          420        -48% │
-      │  铁(mg)         25           12         -52% ← 重点关注 │
-      │  叶酸(μg DFE)   600          350        -42% ← 重点关�� │
-      │  维生素D(μg)    10           2.1        -79% ← 重点关注 │
-      └─────────────────────────────────────────────┘
-
-  ├→ 生成分析结论（自然语言）：
-  │   「昨天钙、铁、叶酸摄入偏低，建议今天多吃：
-  │     ✓ 深绿色蔬菜（菠菜、西兰花）
-  │     ✓ 瘦肉/动物肝脏
-  │     ✓ 豆制品/奶制品」
-  │
-  └→ 写入 data/presets/今日简报_YYYY-MM-DD.json
-       ├ 今日重点关注营养素列表
-       ├ 今日推荐食物类别与份量
-       ├ 体重提醒（如需）
-       └ 与孕妇及家人交谈的建议开场话题
-```
-
-> **批注：** ________
-
----
-
-## 三、核心架构：Loop 驱动（状态机 + 插件注册）
-
-### 3.1 设计理念
-
-PregoPal 不是一个「用户点按钮 → 出结果」的被动应用，而是**有每日生命周期的主动伴侣**。
-
-参考你提供的 `nanobot_core/agent/loop.py` 中的**状态机事件驱动模式**，PregoPal 的 Loop 提取两个核心设计：
-
-1. **TurnState 状态机**（类比 `_process_message` 的 `_state_*` 状态链）— 管理每日生命周期的阶段流转
-2. **可注册的扩展能力**（类比 ToolRegistry）— 每个阶段的具体逻辑由 Plugin 实现
-
-> **批注：** ________
-
-### 3.2 每日生命周期
-
-```
-                         ┌─────────────┐
-                         │   LAUNCH    │  ← 首次启动检查
-                         │   (启动)     │
-                         └──────┬──────┘
-                                │
-                    ┌───────────┴───────────┐
-                    │                       │
-             首次运行今日                已运行过今日
-                    │                       │
-                    ▼                       ▼
-            ┌──────────────┐       ┌──────────────┐
-            │  SUMMARIZE   │       │              │
-            │  (昨日总结)    │       │              │
-            │  ├ 读取饮食日志 │       │              │
-            │  └ 检查体重   │       │              │
-            └──────┬───────┘       │              │
-                   │               │              │
-                   ▼               │              │
-            ┌──────────────┐       │              │
-            │   ANALYZE    │       │              │
-            │  (营养分析)    │       │              │
-            │  └ 对比DRIs  │       │              │
-            └──────┬───────┘       │              │
-                   │               │              │
-                   ▼               │              │
-            ┌──────────────┐       │              │
-            │    BRIEF     │       │              │
-            │  (生成简报)    │       │              │
-            │  └ 写JSON    │       │              │
-            └──────┬───────┘       │              │
-                   │               │              │
-                   ▼               ▼              │
-            ┌──────────────────────────────────┐  │
-            │           INTERACT               │◄─┘
-            │       (白天交互模式)               │
-            │  ├ 声纹识别 → 区分说话人           │
-            │  ├ 对话理解 → 记录饮食/推荐/闲聊    │
-            │  └ 简报注入 → AI 知道今日关注点    │
-            └──────────────┬───────────────────┘
-                           │
-                     用户结束今日
-                           │
-                           ▼
-            ┌──────────────┐
-            │ CONSOLIDATE  │
-            │  (晚间整理)    │  ← 可选（关闭页面时触发）
-            │  ├ 汇总今日    │
-            │  └ 写明日预设  │
-            └──────┬───────┘
-                   │
-                   ▼
-            ┌──────────────┐
-            │     DONE     │
-            └──────────────┘
-```
-
-> **批注：** ________
-
-### 3.3 状态机定义
-
-```python
-# 状态枚举
-class LoopState(Enum):
-    LAUNCH = "launch"           # 启动检查：是否是今日首次运行
-    SUMMARIZE = "summarize"     # 昨日总结：��析昨日饮食/体重
-    ANALYZE = "analyze"         # 营养分析：对比 DRIs
-    BRIEF = "brief"             # 生成今日简报
-    INTERACT = "interact"       # 白天交互模式（等待用户操作）
-    CONSOLIDATE = "consolidate" # 晚间整理
-    DONE = "done"
-
-# 状态转移表（类比 nanobot_core 的 _TRANSITIONS）
-_TRANSITIONS = {
-    (LoopState.LAUNCH, "first_run_today"):  LoopState.SUMMARIZE,
-    (LoopState.LAUNCH, "already_run"):      LoopState.INTERACT,
-    (LoopState.SUMMARIZE, "ok"):            LoopState.ANALYZE,
-    (LoopState.ANALYZE, "ok"):              LoopState.BRIEF,
-    (LoopState.BRIEF, "ok"):                LoopState.INTERACT,
-    (LoopState.INTERACT, "day_ended"):      LoopState.CONSOLIDATE,
-    (LoopState.CONSOLIDATE, "ok"):          LoopState.DONE,
-}
-```
-
-> **批注：** ________
-
-### 3.4 状态处理器
-
-每个状态对应一个 handler（类比 `_state_restore`, `_state_compact`, `_state_run` 等）：
-
-| 状态 | Handler | 功能 |
-|------|---------|------|
-| `LAUNCH` | `_state_launch()` | 检查 `data/presets/` 中是否有今日简报 → 决定首次/已运行 |
-| `SUMMARIZE` | `_state_summarize()` | 遍历执行所有注册在 SUMMARIZE 阶段的 Plugin |
-| `ANALYZE` | `_state_analyze()` | 遍历执行所有注册在 ANALYZE 阶段的 Plugin |
-| `BRIEF` | `_state_brief()` | 遍历执行所有注册在 BRIEF 阶段的 Plugin |
-| `INTERACT` | `_state_interact()` | 等待用户交互（从 Gradio event queue 消费消息） |
-| `CONSOLIDATE` | `_state_consolidate()` | 遍历执行所有注册在 CONSOLIDATE 阶段的 Plugin |
-| `DONE` | `_state_done()` | 清理资源，标记今日完成 |
-
-> **批注：** ________
-
-### 3.5 主循环入口
-
-```python
-# loop.py 核心逻辑
-class PregoPalLoop:
-    def __init__(self):
-        self.plugins = PluginRegistry()
-        self.state = LoopState.LAUNCH
-        self._register_default_plugins()
-    
-    async def run(self) -> None:
-        """主循环入口"""
-        while self.state is not LoopState.DONE:
-            handler_name = f"_state_{self.state.value}"
-            handler = getattr(self, handler_name)
-            event = await handler()
-            next_state = _TRANSITIONS.get((self.state, event))
-            if next_state is None:
-                raise RuntimeError(f"No transition from {self.state} on {event}")
-            self.state = next_state
-    
-    async def _state_summarize(self) -> str:
-        """SUMMARIZE 阶段：执行所有相关插件"""
-        for plugin in self.plugins.get_plugins(LoopStage.SUMMARIZE):
-            await plugin.run(self.context)
-        return "ok"
-```
-
-> **批注：** ________
-
----
-
-## 四、插件系统设计（可扩展性）
-
-### 4.1 插件基类
-
-```python
-# plugins/base.py
-from abc import ABC, abstractmethod
-from dataclasses import dataclass, field
-from enum import Enum
-
-class LoopStage(Enum):
-    """插件可注册的阶段"""
-    SUMMARIZE = "summarize"
-    ANALYZE = "analyze"
-    BRIEF = "brief"
-    CONSOLIDATE = "consolidate"
-
-@dataclass
-class LoopContext:
-    """插件上下文：共享数据容器"""
-    briefing: dict = field(default_factory=dict)    # 今日简报数据
-    weight_data: dict = field(default_factory=dict)  # 体重记录
-    diet_records: list = field(default_factory=list)  # 饮食记录
-    analysis_results: dict = field(default_factory=dict)  # 分析结果
-    errors: list = field(default_factory=list)         # 错误收集
-
-@dataclass
-class PluginResult:
-    """插件执行结果"""
-    success: bool
-    data: dict = field(default_factory=dict)
-    message: str = ""
-
-class LoopPlugin(ABC):
-    """Loop 扩展插件基类 — 所有插件继承此类"""
-    
-    @abstractmethod
-    def stage(self) -> LoopStage:
-        """此插件注册到哪个阶段"""
-    
-    @abstractmethod
-    def name(self) -> str:
-        """插件唯一名称"""
-    
-    @abstractmethod
-    async def run(self, ctx: LoopContext) -> PluginResult:
-        """执行插件逻辑"""
-```
-
-> **批注：** ________
-
-### 4.2 内置插件清单
-
-| 插件 | 类名 | 注册阶段 | 功能 | 数据源 |
-|------|------|---------|------|--------|
-| 昨日饮食总结 | `DietSummaryPlugin` | SUMMARIZE | 读取昨日饮食日志，汇总三餐 | `data/logs/*.md` |
-| 体重检查 | `WeightCheckPlugin` | SUMMARIZE | 检查体重记录，对比 WS/T 801 | `data/logs/*.md` + 用户输入 |
-| DRIs 分析 | `DRIAnalysisPlugin` | ANALYZE | 对比营养素参考摄入量 | DRIs 表 + 昨日饮食 |
-| 简报生成 | `BriefingGeneratorPlugin` | BRIEF | 汇总分析为结构化 JSON | `LoopContext` |
-| 预设写入 | `PresetWriterPlugin` | CONSOLIDATE | 生成明日预设文件 | `data/presets/` |
-
-> **批注：** ________
-
-### 4.3 扩展方式
-
-```python
-# 后续新增功能（如血糖监测）只需两步：
-
-# 1. 写一个新插件
-class BloodSugarPlugin(LoopPlugin):
-    def stage(self) -> LoopStage: return LoopStage.SUMMARIZE
-    def name(self) -> str: return "blood_sugar"
-    async def run(self, ctx: LoopContext) -> PluginResult:
-        # 读取血糖记录 → 分析趋势 → 写入 ctx
-        ...
-
-# 2. 注册到 loop
-loop.plugins.register(BloodSugarPlugin())
-
-# 不需要修改 loop.py 的任何状态机代码
-```
-
-> **批注：** ________
-
----
-
-## 五、整体文件结构
-
-```
-PregoPal/
-├── app.py                          # 主入口：启动 Gradio + Loop
-├── config.py                       # 全局配置（路径/枚举/系统提示词模板）
-├── utils.py                        # 工具函数
-├── loop.py              ← 🆕 新增  # 核心循环引擎（状态机驱动）
-│
-├── plugins/              ← 🆕 新增  # Loop 插件
-│   ├── __init__.py
-│   ├── base.py                     # LoopPlugin 基类 + PluginRegistry
-│   ├── diet_summary.py             # 昨日饮食总结
-│   ├── weight_check.py             # 体重检查（WS/T 801）
-│   ├── dri_analysis.py             # DRIs 营养素对比分析
-│   ├── briefing_generator.py       # 今日简报生成器
-│   └── preset_writer.py            # 预设文件写入
-│
-├── core/                           # AI 核心层（等待 MiniCPM-o 部署）
-│   ├── __init__.py
-│   ├── model_loader.py             # 模型加载器（空接口）
-│   ├── voice_processor.py          # 语音处理器（空接口）
-│   ├── vision_processor.py         # 视觉处理器（空接口）
-│   └── conversation_manager.py     # 对话管理器（空接口）
-│
-├── modules/                        # 业务逻辑层
-│   ├── __init__.py
-│   ├── voiceprint.py               # 声纹识别
-│   ├── meal_recommender.py         # 菜品推荐
-│   ├── diet_logger.py              # 饮食记录 + Markdown 生成
-│   └── nutrition_analyzer.py       # 营养分析 + 可视化
-│
-├── ui/                             # 表现层
-│   ├── __init__.py
-│   └── app_builder.py              # Gradio 界面 + 事件绑定
-│
-├── data/                           # 数据存储
-│   ├── nutrition/
-│   │   └── raw/                    # ← 你已下载的三个 MD 文件
-│   │       ├── 妊娠期妇女体重增长推荐值标准.md
-│   │       ├── 中国孕期妇女膳食指南2022图片转md版.md
-│   │       └── 备孕&孕早中晚三期和哺乳期的所有膳食营养素参考摄入量.md
-│   ├── presets/          ← 🆕 新增  # 每日简报 / 预设文件
-│   ├── voices/                     # 声纹数据
-│   ├── logs/                       # Markdown 饮食日志
-│   └── reports/                    # 导出报告
-│
-├── docs/
-│   ├── 项目理解_技术架构.md         # ← 本文档
-│   └── 开发日志.md
-│
-├── requirements.txt                # 依赖清单
-└── README.md
-```
-
-> **批注：** ________
-
----
-
-## 六、数据流全景
-
-```
-                data/nutrition/raw/
-                ├── 体重标准.md ─────────────┐
-                ├── 膳食指南.md ─────────────┤
-                └── DRIs.md ─────────────────┤
-                                            │
-                    ┌───────────────────────▼──────────────────────┐
-                    │               data/presets/                    │
-                    │               (缓存编译后的结构化数据)          │
-                    │  体重标准.json   膳食指南.json   DRIs.json     │
-                    └──────────────┬────────────────────────────────┘
-                                  │
-                                  ▼
-            ┌──────────────────────────────────────────────────────┐
-            │                   loop.py                             │
-            │  ┌────────────────────────────────────────────────┐   │
-            │  │  状态机驱动 (LAUNCH→SUMMARIZE→ANALYZE→BRIEF)   │   │
-            │  │              ↓ 依次调用 Plugin                  │   │
-            │  │  diet_summary → weight_check → dri_analysis    │   │
-            │  │                    ↓                           │   │
-            │  │           briefing_generator                   │   │
-            │  │                    ↓                           │   │
-            │  │          data/presets/今日简报.json            │   │
-            │  └────────────────────────────────────────────────┘   │
-            └──────────────────────┬───────────────────────────────┘
-                                  │
-                                  ▼
-            ┌──────────────────────────────────────────────────────┐
-            │  ui/app_builder.py (Gradio 界面)                      │
-            │  ┌────────────────────────────────────────────────┐   │
-            │  │  Tab1 声纹识别 │ Tab2 菜品推荐 │ Tab3 饮食记录 │   │
-            │  │  Tab4 营养报告 │ Tab5 关于                      │   │
-            │  │                                                   │   │
-            │  │  今日简报注入对话上下文                             │   │
-            │  │  AI 知道：今天该关注什么营养素                      │   │
-            │  │  该问谁体重？该聊什么话题？                         │   │
-            │  └────────────────────────────────────────────────┘   │
-            └──────────────────────┬───────────────────────────────┘
-                                  │
-                                  ▼
-                    modules/diet_logger.py (记录新数据)
-                    modules/meal_recommender.py (膳食指南约束)
-                    modules/nutrition_analyzer.py (DRIs 对比)
-                                  │
-                                  ▼
-                    次日 loop.py 再次启动 → 循环
-```
-
-> **批注：** ________
-
----
-
-## 七、技术栈一览
-
-| 层级 | 技术 | 用途 |
-|------|------|------|
-| 核心模型 | **MiniCPM-o 4.5**（统一多模态模型） | 全双工推理：视觉+语音+文本+语音输出 |
-| 前端框架 | **Gradio 6.x** | Web 界面，实时对话交互 |
-| 声纹识别 | Whisper-medium encoder embedding（优先）| 说话人身份识别 |
-| 频谱方案 | NumPy + SoundFile（备选 fallback） | 声纹识别兜底 |
-| 数据存储 | JSON + Markdown | 饮食记录 + 报告存档 + 每日简报 |
-| 营养标准 | 三个 MD 文件（已下载） | 体重标准/膳食指南/DRIs |
-| 循环引擎 | 自研状态机 + 插件注册 | 每日生命周期管理 |
-| 部署平台 | HuggingFace Spaces（目前）+ Modal（后续） | 云端部署 |
-
-> **批注：** ________
-
----
-
-## 八、待讨论问题清单
-
-> 📝 下表汇总了本文档中需要你决策的问题。请在 `____` 处标注你的意见（如需更多讨论，在对应小节批注区补充）。
-
-| # | 问题 | 你的选择 / 意见 |
-|---|------|----------------|
-| 1 | **Loop 启动时机**：Gradio 启动时先跑完 Loop 总结阶段再开服务（A）/ 用户打开页面时才触发（B） | ________ |
-| 2 | **简报承载形式**：JSON 文件落盘作为中介（A）/ 仅内存变量不落盘（B） | ________ |
-| 3 | **Loop 复杂度边界**：只需管好每日生命周期 3~5 个阶段，约 200~300 行（同意）/ 需要更复杂（请说明） | ________ |
-| 4 | **插件优先级**：DietSummary P0 / WeightCheck P0 / DRIAnalysis P0 / BriefingGenerator P0 / PresetWriter P1（需要调整？） | ________ |
-| 5 | **体重数据来源**：用户手动输入（A）/ 语音对话 AI 询问记录（B）/ 蓝牙同步未来扩展（C） | ________ |
-| 6 | **core/ 层处理**：现阶段 Loop 直接调用 modules/ 规则引擎，core/ 保持空接口等 MiniCPM-o（同意？） | ________ |
-| 7 | **还有什么我没考虑到的问题？** | ________ |
-
----
-
-*文档生成时间：2026-06-08 | v4 - 引入 Loop 驱动架构 + 三文档操作方案*

docs/deploy_success_report.md

@@ -0,0 +1,205 @@
+# 🚀 PregoPal × MiniCPM-o-4_5 Modal 部署成功报告
+
+> **状态**: ✅ 已成功部署到 Modal (T4 GPU)
+> **日期**: 2026-06-09 ~ 2026-06-10
+> **API URL**: `https://andrew-jiabin--prego-pal-minicpm-serve.modal.run`
+> **GPU**: T4 (16GB VRAM, $0.50/hr) ← 从 A100 ($1.50/hr) 降级
+
+---
+
+## 1. 最终架构
+
+```
+┌─────────────┐     HTTP      ┌──────────────────────────────────┐
+│ prego-pal   │ ──────────→   │  Modal T4 (asgi_app)             │
+│ (Gradio UI) │               │  ├── FastAPI (端点包装)           │
+└─────────────┘               │  └── llama-cpp-python (CUDA)     │
+                              │       ↕                          │
+                              │  Modal Volume (GGUF 模型持久化)   │
+                              └──────────────────────────────────┘
+```
+
+## 2. 关键决策与经验
+
+### 2.1 预编译 wheel vs 源码编译
+
+| 方案 | 构建时间 | 稳定性 | 最终选择 |
+|------|---------|--------|---------|
+| **预编译 llama-cpp-python wheel** | ~1min ✅ | 稳定 ✅ | **✅ 采用** |
+| 源码编译 llama.cpp + llama-server | ~8min | 易踩坑 | ❌ 放弃 |
+
+**核心经验**: 只要最终目标是 Python 调用，`llama-cpp-python` 的预编译 CUDA wheel (`extra-index-url=https://ggml-org.github.io/llama-cpp-python/whl/cu121`) 就足够了，完全不需要走源码编译路线。
+
+### 2.2 为什么预编译 wheel 能跑
+
+```
+deploy.py (FastAPI) → llama-cpp-python (Llama class)
+                          ↕
+                    MiniCPM-o-4_5 GGUF (Q4_K_M)
+                          ↕
+                    CUDA (T4 GPU, n_gpu_layers=-1)
+```
+
+- llama-cpp-python 内部封装了完整的 llama.cpp C++ 后端
+- 通过 `mmproj=` 参数挂载视觉投影层，支持多模态
+- GGUF 格式量化模型 (Q4_K_M) 在 T4 上推理速度 ~15-25 tok/s
+
+### 2.3 T4 降级可行
+
+| 资源 | 用量 | T4 容量 |
+|------|------|---------|
+| 主模型 (Q4_K_M) | ~4.7 GB | 16 GB |
+| Vision mmproj | ~0.5 GB | |
+| KV Cache (8192 ctx) | ~1 GB | |
+| **总计** | **~6.2 GB** | **余量 >60%** |
+
+### 2.4 镜像构建关键
+
+```python
+_image = (
+    Image.debian_slim(python_version="3.11")
+    .pip_install("fastapi", "uvicorn[standard]", "httpx", "numpy", "Pillow")
+    .pip_install(
+        "llama-cpp-python",                               # ← 预编译 wheel
+        extra_index_url="https://ggml-org.github.io/llama-cpp-python/whl/cu121",
+    )
+    .run_commands(
+        "python -c 'import llama_cpp; print(\"llama-cpp-python OK\")'",
+    )
+)
+```
+
+**构建时间**: ~45秒（纯 pip install，无编译）
+
+---
+
+## 3. 最终 deploy.py 核心逻辑
+
+```python
+# deploy.py 中的关键参数
+@app.function(
+    image=_image,
+    volumes={MODEL_DIR: model_volume},   # 挂载 Volume
+    gpu="T4",                             # ← T4 降级
+    timeout=1200,
+    scaledown_window=300,                 # 5min 空闲缩容
+)
+@modal.concurrent(max_inputs=10)          # 10 并发
+@asgi_app()
+def serve():
+    # 模型加载
+    llm = Llama(
+        model_path="/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",
+        n_gpu_layers=-1,     # 全部层到 GPU
+        n_ctx=8192,          # 8K 上下文
+        verbose=False,
+    )
+    
+    # 暴露端点: POST /v1/chat/completions (OpenAI 兼容)
+    #          POST /v1/vision (多模态)
+    #          GET  /health (健康检查)
+```
+
+完整代码见 `modal_deploy/deploy.py`。
+
+---
+
+## 4. 踩坑与修复
+
+### 坑①：`find_mmproj_files()` 搜索到 9 个 GGUF
+
+**症状**: 旧代码递归搜索所有 `.gguf` 文件并全部作为 `--mmproj` 传入，llama-server 启动失败
+
+**修复**: 显式指定 vision mmproj 路径，不自动搜索
+
+```python
+# ❌ 错误做法
+mmproj_files = find_mmproj_files(MODEL_SUBDIR)  # 找到 9 个 GGUF!
+llama_server_cmd += [f"--mmproj", mmproj_file for mmproj_file in mmproj_files]
+
+# ✅ 正确做法
+VISION_MMPROJ = "vision/MiniCPM-o-4_5-vision-F16.gguf"
+if os.path.isfile(os.path.join(MODEL_SUBDIR, VISION_MMPROJ)):
+    kwargs["mmproj"] = os.path.join(MODEL_SUBDIR, VISION_MMPROJ)
+```
+
+### 坑②：源码编译 llama.cpp 构建超 8 分钟
+
+**症状**: `modal deploy` 时构建镜像耗时 458 秒，且 cmake 步骤容易超时
+
+**修复**: 改用预编译 llama-cpp-python wheel，构建时间降至 ~45 秒
+
+### 坑③：Volume 路径不匹配
+
+**症状**: 模型路径 `/MiniCPM-o-4_5-gguf/...` 需要子目录前缀
+
+**修复**:
+```python
+MODEL_SUBDIR = f"{MODEL_DIR}/MiniCPM-o-4_5-gguf"
+```
+
+### 坑④：500 Internal Server Error
+
+**症状**: 模型加载成功但 API 返回 500
+
+**修复**: 增加 try/except + traceback 日志��定位到参数拼写错误
+
+---
+
+## 5. 测试结果
+
+| 测试项 | 结果 |
+|--------|------|
+| 中文对话 | ✅ "你好，我是 MiniCPM-o" |
+| 英文对话 | ✅ "Paris" |
+| 健康检查 GET /health | ✅ 200 |
+| 模型列表 GET /v1/models | ✅ 200 |
+| Streaming SSE | ✅ 逐 token 输出 |
+| 冷启动时间 | ~40-60s |
+| 推理速度 (T4) | ~15-25 tok/s |
+
+---
+
+## 6. 命令行速查
+
+```bash
+# 部署
+modal deploy modal_deploy.deploy
+
+# 开发模式
+modal serve modal_deploy.deploy
+
+# 测试推理
+modal run modal_deploy.deploy::test_inference
+
+# 查看日志
+modal app logs prego-pal-minicpm
+
+# 上传模型
+modal volume put minicpm-o-4_5-models ./models/MiniCPM-o-4_5-gguf /
+
+# 查看 Volume
+modal volume ls minicpm-o-4_5-models /MiniCPM-o-4_5-gguf
+```
+
+## 7. 成本对比
+
+| GPU | 单价/小时 | 每次请求(2s) | 每月 1000 次 |
+|-----|----------|-------------|-------------|
+| **T4** (当前) | **$0.50** | **$0.00028** | **$0.28** |
+| A100 (旧) | $1.50 | $0.00083 | $0.83 |
+| **节省** | **67%** | **67%** | **67%** |
+
+---
+
+## 8. 文件清单
+
+| 文件 | 说明 |
+|------|------|
+| `modal_deploy/deploy.py` | **主部署文件** — FastAPI + llama-cpp-python |
+| `modal_deploy/client.py` | Python API 客户端 (OpenAI 兼容) |
+| `modal_deploy/README.md` | 部署文档 |
+| `core/model_loader.py` | 项目集成层 (默认走远端 API) |
+| `_test_inference.py` | 测试脚本 |
+| `docs/部署经验_Modal_MiniCPM-o.md` | 旧版部署经验（含源码编译方案） |