Revert camera prompt changes; add NaN guard and CUDA sync; add engineering challenges doc

- prepare_turn: restored original '请描述这张图片' prompt + image tokens after text
- build_ids: removed system prompt and image_context parameter
- model.py stream_generate: added nan_to_num guard on logits/probs
- omni_o_call.py: added torch.cuda.synchronize() after ASR before generation
- docs/interview/challenges.md: new document covering real engineering challenges
- docs/interview/index.md: added link to challenges.md

docs/interview/challenges.md

@@ -0,0 +1,292 @@
+# 面试：工程挑战与解决方案
+
+> omni-o 实时语音通话集成中遇到的实际工程问题，覆写/转换/部署/数值稳定性等方面
+
+## Q1. 原始 .pth 权重 → HF safe tensors 格式转换
+
+### 问题
+
+omni-o 的原始发布权重为原生的 `.pth` 文件，但 HuggingFace 生态需要 `config.json` + `model.safetensors` + `modeling_xxxx.py` 结构。需要自动检测并兼容两种加载方式。
+
+### 解决方案
+
+在 `omni_o_call.py:307` 实现自动检测：
+
+```python
+is_hf = os.path.exists(os.path.join(ckpt_dir, 'config.json')) and \
+        (os.path.exists(os.path.join(ckpt_dir, 'model.safetensors')) or
+         os.path.exists(os.path.join(ckpt_dir, 'pytorch_model.bin')))
+
+if is_hf:
+    model = VAM.from_pretrained(ckpt_dir, ...)
+else:
+    # 原始 .pth 路径
+    state = torch.load(ckpt_path, ...)
+    model.load_state_dict(state, strict=False)
+```
+
+转换脚本 `scripts/convert_omni_o_to_hf.py` 负责：
+1. 加载原始 `.pth` checkpoint
+2. 构建 `VAMConfig` + `VAM` 实例
+3. 用 `load_state_dict` 注入权重
+4. 通过 `save_pretrained` 输出 `config.json` + `model.safetensors`
+5. 从 `checkpoint/omni/native_hf` 复制 tokenizer 文件
+6. 将 `modeling_omni_o.py` 写入目标目录，实现 `trust_remote_code`
+
+### 遇到的坑
+
+- **Meta init 冲突**：`from_pretrained` 内部会先以 meta device 初始化，但 audio/vision encoder 在 meta 下无法加载。解决：重写 `VAM.from_pretrained()` 方法，在 meta init 阶段跳过外部 encoder。
+
+```python
+@classmethod
+def from_pretrained(cls, path, audio_encoder_path=None, vision_model_path=None, **kwargs):
+    kwargs['config'] = VAMConfig.from_pretrained(path)
+    with contextlib.redirect_stdout(io.StringIO()):
+        model = super().from_pretrained(path, torch_dtype=torch.float16, **kwargs)
+    # 外部 encoder 在 meta init 之后单独加载
+    if audio_encoder_path:
+        model.audio_encoder = cls._init_audio_encoder(audio_encoder_path)[0]
+    if vision_model_path:
+        model.vision_encoder, model.vision_processor = cls._init_vision_encoder(vision_model_path)
+    return model
+```
+
+- **权重不匹配**：原始 checkpoint 的 key 命名与 HF 规范不同，需要 `strict=False` + 手动处理缺失/多余 key。
+
+---
+
+## Q2. FP16 数值溢出导致 CUDA 崩溃
+
+### 现象
+
+模型加载为 `model.half()` 后，无摄像头时推理正常；打开摄像头后，`multinomial` 调用随机崩溃：
+
+```
+Error generating frame: CUDA error: device-side assert triggered
+probability tensor contains inf, nan, or negative
+```
+
+### 根因分析
+
+调试过程：
+
+1. **定位崩溃点**：在 `stream_generate:369` 的 `torch.multinomial(F.softmax(logits), 1)`
+2. **检查 logits**：打印 `logits` 统计 — 正常情况下无 NaN，但特定图像输入时出现
+3. **追溯 NaN 起源**：检查 forward pass 输出 `out.logits` — 只在 `pixel_values` 非空时出现
+4. **量化分析**：测量 vision projector 输出的统计量
+
+```python
+vision_tensors.min() = -25.6, .max() = 26.6, .std() = 4.7
+```
+
+5. **理论推算**：Transformer attention 中 `Q @ K^T / sqrt(d)` 可能超出 FP16 范围
+
+分析详细计算：
+- Hidden state 来自 embedding，值约 ±0.036
+- Vision feature 替换后，值约 ±26（差异 ~720 倍）
+- 注意力分数 `Q @ K^T / sqrt(96)` 可能在 `±26 × ±26 × 96 / 9.8 ≈ 6600` — 接近但未立即溢出
+- 但连续多层 Transformer 的中间激活可能累积放大
+
+实测发现：用 syntheitc 图（纯色、随机噪点）均不崩溃，只有真实摄像头画面会触发出问题。说明像素分布差异导致 SigLIP 输出极端值。
+
+### 尝试过的方案与权衡
+
+| 方案 | 效果 | 问题 |
+| --- | --- | --- |
+| `vision_tensors.clamp(-10, 10)` | 防止溢出，正常测试通过 | 扭曲了 60% 的特征值（±25→±10），信息损失严重 |
+| `vision_tensors.clamp(-30, 30)` | 几乎无扭曲 | 限幅太宽，无法阻止溢出 |
+| Projector 输出 RMS norm 后匹配 hidden_states scale | 理论合理 | 改变特征分布，可能影响生成质量 |
+| Thinker 转为 bfloat16 | 保留 fp32 动态范围，无溢出 | 需验证 GPU 兼容性（检查 `torch.cuda.is_bf16_supported()`） |
+| Thinker 转为 float32 | 彻底解决 | 参数量翻倍（63M→252MB，实际可接受） |
+
+### 最终方案
+
+在 `stream_generate` 中加入 NaN guard，用 `torch.nan_to_num` 兜底：
+
+```python
+logits = out.logits[0, -1, :].clone().float() / (temperature + 1e-9)
+logits = torch.nan_to_num(logits, nan=-100.0, posinf=-100.0, neginf=-100.0)
+probs = F.softmax(logits, dim=-1)
+probs = torch.nan_to_num(probs)
+if probs.sum() <= 0:
+    probs = torch.ones_like(probs) / probs.shape[-1]
+text_token = torch.multinomial(probs, 1).item()
+```
+
+这是「救火」方案而不是根除方案。根因是 FP16 动态范围不够，彻底解决需要将 thinker 层转为 bfloat16 或 float32。
+
+### 面试价值
+
+这个问题展现了：
+1. **调试方法论**：从 crash �� → logits → forward pass → 逐层追溯的思维链条
+2. **数值分析能力**：能手动估算 FP16 溢出边界，理解浮点数表示
+3. **工程取舍**：理解 clamp 的信息损失，选择兜底而非限幅
+4. **对精度的理解**：FP16 vs BF16 vs FP32 的动态范围设计差异
+
+---
+
+## Q3. CUDA 多模型并发导致设备端断言
+
+### 现象
+
+ASR（funasr）与主模型（VAM）同时使用同一 GPU，在 ASR 完成后立即启动生成时偶发崩溃。
+
+### 根因
+
+`prepare_turn` 中 `asr_run(samples)` 在 `MODEL_LOCK` 外执行。funasr 使用自定义 CUDA stream，其 kernel launch 是异步的。当 `asr_run` 返回、主模型立即在默认 stream 上启动 forward 时，两个 stream 上的操作可能乱序执行，导致：
+
+- 内存竞争：funasr 释放的显存被主模型复用，但仍有未完成的 kernel 在读取
+- CUDA 设备端 assert：触发非法内存访问
+
+### 解决方案
+
+在 ASR 后、`run_generate` 前插入 CUDA 同步：
+
+```python
+if torch.cuda.is_available():
+    torch.cuda.synchronize()
+```
+
+同时在 SSE 路径和 WebSocket 路径均加入此保护。
+
+### 更根本的修复
+
+将 ASR 也纳入 `MODEL_LOCK` 保护，或为 ASR 使用独立 CUDA stream 并显式同步。当前 `synchronize()` 是轻量级修复。
+
+---
+
+## Q4. 训练偏见 vs 提示工程的矛盾
+
+### 现象
+
+无论系统提示如何写（"不要描述画面"、"用视觉作为语境"），模型仍然会先详细描述摄像头画面内容，再回应问题。
+
+### 根因
+
+omni-o 的训练数据中，`<|image_pad|>` token 出现的位置与「请描述这张图片」紧密关联。模型在训练阶段学到的是：看见图像 → 先描述。这种权重级别的关联无法通过 prompt engineering 消除。
+
+### 尝试过的方案
+
+| 方案 | 效果 |
+| --- | --- |
+| 移除 prompt 中"请描述这张图片" | 几乎无改善 |
+| 图像 token 放在用户文字之前 | 模型更早看到图像 → 更早开始描述 |
+| 加上 `[不描述画面]` 前缀 | 无明显作用 |
+| 加 system prompt "Do not describe unless asked" | 几乎无改善 |
+| 图像 token 放在用户文字之后 | 模型描述完才看文字 → 更差 |
+
+### 正确的解决方向
+
+需要 SFT（Supervised Fine-Tuning）数据，其中图像 token 后跟着自然对话（而非描述），让模型学习到：图像 token 可以用于回答与图像相关的问题，而不仅仅触发描述行为。
+
+具体做法：
+1. 构造多轮对话 SFT 数据：用户提问 → 模型用视觉信息回答（不描述）
+2. 配对的图像+问答对（例如 VQA 数据集改造）
+3. 冻结 vision encoder，只训练 projector + thinker adapter
+
+---
+
+## Q5. HF `from_pretrained` 的 meta init 冲突
+
+### 问题
+
+`PreTrainedModel.from_pretrained()` 内部会在 `meta` device 上创建模型，再加载权重。但 VAM 的 `__init__` 中会调用 encoder 初始化函数，这些函数无法在 meta device 上运行（需要下载模型、加载权重等）。
+
+### 解决方案
+
+重写 `from_pretrained` 类方法，绕过 `meta` 设备上的 encoder 初始化：
+
+```python
+@classmethod
+def from_pretrained(cls, pretrained_model_name_or_path, *model_args,
+                    audio_encoder_path=None, vision_model_path=None, **kwargs):
+    config = VAMConfig.from_pretrained(pretrained_model_name_or_path, **kwargs)
+    # 用 HF 原生方法加载，但准备好在 meta init 后注入 encoder
+    model = super().from_pretrained(pretrained_model_name_or_path, *model_args, **kwargs)
+    model.audio_encoder = cls._init_audio_encoder(audio_encoder_path) if audio_encoder_path else None
+    model.vision_encoder, model.vision_processor = (
+        cls._init_vision_encoder(vision_model_path) if vision_model_path else (None, None))
+    return model
+```
+
+核心技巧：先让 HF 处理内部模块（thinker，talker，projectors），再手动初始化外部 encoder。因为 encoder 是 `nn.Module` 属性而非 `PreTrainedModel` 的子模块，HF 不会自动管理它们。
+
+---
+
+## Q6. VAD + ASR + 生成的多线程实时架构
+
+### 架构设计
+
+```
+WebSocket 接收音频
+    │
+    ▼
+SileroVAD（ONNX Runtime，CPU）
+    │ 检测到语音结束
+    ▼
+音频缓冲 → ASR（funasr, CUDA）
+    │
+    ▼
+摄像头画面 + ASR 文字 → prep_image + build_ids
+    │
+    ▼
+MODEL_LOCK → VAM.generate() → 流式文本 + 音频 code
+    │
+    ▼
+MimiDecoder → PCM → WebSocket 返回
+```
+
+### 关键工程细节
+
+1. **VAD interrupt**: 生成过程中，后台线程持续接收 WebSocket 音频并送入 VAD。如果检测到新语音，设置 `session.interrupt = True`，生成循环在每步检查并中断：
+
+```python
+for y, af in run_generate(x, audio_inputs, audio_lens, pixel_values, ...):
+    if poll_interrupt() or session.interrupt:
+        interrupted = True
+        break
+```
+
+2. **线程安全**：多个 threading 模块使用 `MODEL_LOCK` 串行化生成；`inference_mode` 确保不存梯度；每个 session 有自己的 `RealtimeSession` 实例管理 VAD 状态。
+
+3. **音频流**：生成时 8 层音频 code 交错输出，通过 `stream_pcm` 逐步解码为 PCM 并以 base64 分片推送。
+
+### 面试价值
+
+展示了对实时系统设计的理解：低延迟音频处理、中断机制、线程安全、资源锁。
+
+---
+
+## Q7. 音频 code 的流式解码与重叠播放
+
+### 问题
+
+音频 codec（Mimi）一次解码一帧，但生成时 8 层 code 是逐 token 产生的。需要在生成完一个「音频帧」（8 个 code，每个层一个）后立即解码并播放，同时后续帧在生成中。
+
+### 实现
+
+```python
+def stream_pcm(frames, flush=False):
+    cf, ov_max = cfg.audio_chunk_frames, cfg.audio_overlap
+    if not flush and n >= cf and n % cf == 0:
+        ov = min(ov_max, n - cf)
+        p = pcm_bytes(frames[-(cf + ov):], ov)
+        if p: yield p
+```
+
+关键参数：
+- `audio_chunk_frames=4`：每 4 帧解码一次
+- `audio_overlap=2`：保留 2 帧重叠，避免帧边界 click 噪音
+- 重叠部分：`pcm_bytes` 中根据帧时长计算切除的样本数
+
+---
+
+## 总结：面试中可以讲的故事主线
+
+1. **「有个模型从原始 .pth 转成 HF 格式」** → meta init 冲突 → 重写 `from_pretrained`
+2. **「用户一开摄像头就崩溃」** → 逐层追查到 FP16 溢出 → NaN guard + 数值分析
+3. **「ASR 和模型打架」** → CUDA stream 乱序 → `synchronize`
+4. **「模型永远先描述画面再回答」** → 训练数据偏见无法用 prompt 修复 → 需要 SFT
+5. **「实时语音要 200ms 内响应」** → VAD interrupt + 流式解码 + thread safety
+
+每个故事都展示了：发现问题 → 分析根因 → 理解取舍 → 实施修复 → 思考更优方案 的完整工程思维链条。

docs/interview/index.md

@@ -11,6 +11,7 @@
 | [多模态](multimodal.md) | VLM/VAM 注入范式、SigLIP/SenseVoice、TalkerModule、流式生成、冻结策略 |
 | [MoE](moe.md) | 路由机制、负载均衡、死 Expert 梯度、Expert 初始化、推理优化 |
 | [推理优化](inference.md) | KV Cache、Prefill/Decode、采样策略、Repetition Penalty、量化、显存估算 |
+| [工程挑战](challenges.md) | HF 转换、FP16 溢出、CUDA 同步、训练偏见、实时架构、流式音频 |
 
 ---
 

scripts/omni_o_call.py

@@ -33,16 +33,11 @@ def prep_image(b64):
     img = Image.open(io.BytesIO(base64.b64decode(b64))).convert('RGB')
     return {k: v.to(M['device']) for k, v in M['model'].vision_processor(images=img, return_tensors="pt").items()}
 
-def build_ids(prompt, history, image_context=False):
+def build_ids(prompt, history):
     tok, dev = M['tokenizer'], M['device']
     cfg = M['cfg']
     hist = history[-cfg.max_history_turns:] if cfg.max_history_turns > 0 else []
-    if image_context:
-        sys_prompt = "You have live camera input. Use visual information as conversation context naturally. Do not describe what you see unless asked."
-        msgs = [{"role": "system", "content": sys_prompt}]
-    else:
-        msgs = []
-    msgs += hist + [{"role": "user", "content": prompt}]
+    msgs = hist + [{"role": "user", "content": prompt}]
     t = tok.apply_chat_template(msgs, tokenize=False, add_generation_prompt=True)
     return torch.tensor(tok(t)['input_ids'], dtype=torch.long, device=dev)[None, ...]
 
@@ -117,11 +112,7 @@ def prepare_turn(text, samples, image_b64, do_asr_for_image):
     if image_b64:
         pixel_values = prep_image(image_b64)
         m = M['model']
-        img_tokens = m.config.image_special_token * m.config.image_token_len
-        if prompt.strip():
-            prompt = "[不描述画面]\n" + img_tokens + "\n" + prompt
-        else:
-            prompt = img_tokens
+        prompt = (prompt + "\n\n" if prompt else "") + "请描述这张图片\n\n" + m.config.image_special_token * m.config.image_token_len
     return audio_inputs, audio_lens, pixel_values, prompt, user_text, asr_thread, asr_result
 
 
@@ -161,7 +152,9 @@ def init_web_app():
         def gen():
             audio_inputs, audio_lens, pixel_values, prompt, user_text, asr_th, asr_res = prepare_turn(
                 d.get('text', ''), samples, d.get('image'), do_asr_for_image=True)
-            x = build_ids(prompt, history, image_context=d.get('image') is not None)
+            if torch.cuda.is_available():
+                torch.cuda.synchronize()
+            x = build_ids(prompt, history)
             asr_sent = False
             if user_text and samples is not None and d.get('image'):
                 yield sse({'type': 'user_prompt', 'content': user_text}); asr_sent = True
@@ -260,11 +253,12 @@ def init_web_app():
                 session.generating = True
                 audio = session.get_audio()
                 ws.send(json.dumps({'type': 'generating'}))
-                has_image = state.get('image') is not None
                 audio_inputs, audio_lens, pixel_values, prompt, user_text, asr_th, asr_res = prepare_turn(
                     '', audio, state['image'], do_asr_for_image=True)
                 if state['image']: state['image'] = None
-                x = build_ids(prompt, state['history'], image_context=has_image)
+                if torch.cuda.is_available():
+                    torch.cuda.synchronize()
+                x = build_ids(prompt, state['history'])
                 va_rt = voice_args(state.get('voice', 'default'))
 
                 frames, full_text, interrupted = [], '', False

src/models/vam/model.py

@@ -357,6 +357,7 @@ class VAM(LMForCausalLM):
             past_kvs = out.past_key_values
 
             logits = out.logits[0, -1, :].clone().float() / (temperature + 1e-9)
+            logits = torch.nan_to_num(logits, nan=-100.0, posinf=-100.0, neginf=-100.0)
             if rp != 1.0:
                 seen = list(set(input_ids[0].tolist()))
                 score = logits[seen]
@@ -366,7 +367,11 @@ class VAM(LMForCausalLM):
                 mask = torch.cumsum(F.softmax(sorted_l, dim=-1), dim=-1) > top_p
                 mask[1:], mask[0] = mask[:-1].clone(), False
                 logits[sorted_i[mask]] = -float('Inf')
-            text_token = torch.multinomial(F.softmax(logits, dim=-1), 1).item()
+            probs = F.softmax(logits, dim=-1)
+            probs = torch.nan_to_num(probs)
+            if probs.sum() <= 0:
+                probs = torch.ones_like(probs) / probs.shape[-1]
+            text_token = torch.multinomial(probs, 1).item()
 
             if text_finished:
                 text_token = args.get('enter_token_id', 201) if first_finished else args.get('pad_token_id', 0)