重构项目为LLM 驱动

.agents/docs/error-experience/2026-06-08-LlamaIndex多模态消息格式错误.md

@@ -0,0 +1,59 @@
+---
+last_reviewed: 2026-06-09
+---
+
+# LlamaIndex 多模态消息格式错误
+
+## 错误现象
+
+```
+pydantic_core._pydantic_core.ValidationError: 2 validation errors for ChatMessage
+blocks.0
+  Unable to extract tag using discriminator 'block_type' [type=union_tag_not_found, ...
+blocks.1
+  Unable to extract tag using discriminator 'block_type' [type=union_tag_not_found, ...
+```
+
+## 触发条件
+
+- llama-index-core >= 0.14.x
+- 使用 `ChatMessage` 构造多模态消息（文本 + 图片）
+- 传入 OpenAI 格式的 `content` 列表：`[{"type": "text", ...}, {"type": "image_url", ...}]`
+
+## 原因
+
+`llama-index-core 0.14.x` 重构了 `ChatMessage` 的内部结构：
+
+| 版本 | 字段 | 多模态 content 格式 |
+|------|------|-------------------|
+| 0.14.x | `role`, `blocks`, `additional_kwargs` | `TextBlock` / `ImageBlock` 实例 |
+| 旧版本 | `role`, `content` | OpenAI 风格字典列表 |
+
+底层 Pydantic 模型使用 `block_type` 作为 union discriminator，OpenAI 格式的 `{"type": "text", ...}` 字典不包含该字段，导致验证失败。
+
+## 修复方法
+
+**正确写法（llama-index 原生 blocks 格式）：**
+
+```python
+from llama_index.core.llms import ChatMessage
+from llama_index.core.base.llms.types import ImageBlock, TextBlock
+
+messages = [
+    ChatMessage(role="system", content=system_prompt),
+    ChatMessage(
+        role="user",
+        blocks=[
+            TextBlock(text="请分析这张图片"),
+            ImageBlock(
+                url=f"data:image/jpeg;base64,{image_b64}",
+                detail="high",
+            ),
+        ],
+    ),
+]
+```
+## 适用版本
+
+- llama-index-core: 0.14.22
+- llama-index-llms-openai-like: 0.7.2