# 图片生成问题调试指南

> 问题：点击生成图片后直接提示"未成功生成任何图片"
> 创建日期：2026-01-28

---

## 🔍 问题分析

### 可能的原因

1. **API Key 未配置或配置错误**
   - 通义万相 API Key 未在侧边栏配置
   - API Key 格式错误
   - API Key 已过期或无效

2. **API 调用失败**
   - 网络连接问题
   - API 服务不可用
   - 免费额度已用完
   - API 限流

3. **Prompt 生成失败**
   - LLM 调用失败
   - Prompt 为空或格式错误
   - 内容不合规

4. **API 响应解析错误**
   - 响应格式不符合预期
   - `response.output.results` 为空
   - `image_url` 为空

5. **异常被静默捕获**
   - 异常被捕获但没有正确显示
   - 错误信息丢失

---

## ✅ 已添加的调试功能

### 1. 详细的错误信息显示

在图片生成失败时，现在会显示：
- **错误类型**：API调用失败、Prompt为空、响应解析错误等
- **错误详情**：具体的错误消息
- **调试信息**：
  - Prompt 内容（前200字符）
  - API Key 配置状态
  - 异常堆栈跟踪

### 2. 输入验证

- ✅ 验证 Prompt 不为空
- ✅ 验证 API 响应不为空
- ✅ 验证 `image_url` 存在
- ✅ 验证 `response.output.results` 不为空

### 3. 异常处理增强

- ✅ 捕获所有异常并显示详细信息
- ✅ 显示异常堆栈跟踪
- ✅ 区分不同类型的错误

---

## 🔧 调试步骤

### 步骤1：检查 API Key 配置

1. 打开侧边栏 **⚙️ 全局配置**
2. 找到 **🖼️ 通义万相（图片生成）** 部分
3. 确认 API Key 已正确配置
4. 点击 **应用配置**

### 步骤2：查看错误信息

如果生成失败，点击 **查看详细错误信息** 或 **查看异常详情**，查看：
- 错误消息
- Prompt 内容
- API Key 配置状态
- 异常堆栈跟踪

### 步骤3：检查常见问题

#### 问题1：API Key 未配置
**症状**：错误信息显示"API Key 配置: 未配置"
**解决**：在侧边栏配置通义万相 API Key

#### 问题2：API 调用失败
**症状**：错误信息显示"API调用失败，状态码：XXX"
**可能原因**：
- 网络连接问题
- API 服务不可用
- 免费额度已用完
- API 限流

**解决**：
- 检查网络连接
- 检查 API 服务状态
- 检查免费额度
- 等待后重试

#### 问题3：Prompt 为空
**症状**：错误信息显示"图片生成 Prompt 为空"
**可能原因**：
- LLM 调用失败
- 内容为空
- Prompt 生成异常

**解决**：
- 检查内容是否为空
- 检查 LLM 配置
- 重试生成

#### 问题4：响应解析错误
**症状**：错误信息显示"生成成功但未返回图片URL"
**可能原因**：
- API 响应格式变化
- `response.output.results` 为空
- `image_url` 为空

**解决**：
- 查看详细错误信息中的响应内容
- 检查 API 文档是否有变化
- 联系技术支持

---

## 📋 代码修改说明

### 修改1：增强错误处理（geo_tool.py）

**位置**：第3670-3700行（智能生成模式）

**修改内容**：
- 添加 Prompt 验证
- 添加 result 验证
- 添加 image_url 验证
- 添加详细的错误信息显示
- 添加异常堆栈跟踪

### 修改2：增强错误处理（geo_tool.py）

**位置**：第3792-3820行（基于描述生成模式）

**修改内容**：
- 与智能生成模式相同的错误处理增强

### 修改3：增强 API 响应处理（multimodal_prompt.py）

**位置**：第706-740行

**修改内容**：
- 验证 `response.output.results` 不为空且长度 > 0
- 验证 `image_url` 不为空
- 添加详细的错误信息
- 包含响应状态码、消息、错误码、请求ID等

---

## 🧪 测试建议

### 测试1：正常流程
1. 配置正确的 API Key
2. 生成内容
3. 点击"生成图片"
4. 应该成功生成图片

### 测试2：API Key 未配置
1. 不配置 API Key
2. 点击"生成图片"
3. 应该显示"请在侧边栏配置中设置通义万相 API Key"

### 测试3：API 调用失败
1. 配置错误的 API Key
2. 点击"生成图片"
3. 应该显示详细的错误信息

### 测试4：Prompt 为空
1. 使用空内容
2. 点击"生成图片"
3. 应该显示"图片生成 Prompt 为空"错误

---

## 📝 常见错误信息对照表

| 错误信息 | 可能原因 | 解决方法 |
|---------|---------|---------|
| "图片生成 Prompt 为空" | LLM 调用失败或内容为空 | 检查内容、检查 LLM 配置 |
| "图片生成 API 返回空结果" | API 调用异常 | 检查网络、检查 API Key |
| "API调用失败，状态码：XXX" | API 服务错误 | 检查 API 服务状态、检查免费额度 |
| "生成成功但未返回图片URL" | API 响应格式错误 | 查看详细错误信息、检查 API 文档 |
| "图片生成成功但图片URL为空" | API 响应中缺少 URL | 查看详细错误信息、联系技术支持 |
| "未安装 dashscope 库" | 缺少依赖库 | 运行：pip install dashscope |

---

## 🔍 进一步调试

如果问题仍然存在，请：

1. **查看详细错误信息**
   - 点击"查看详细错误信息"或"查看异常详情"
   - 复制错误信息

2. **检查日志**
   - 查看浏览器控制台
   - 查看 Streamlit 日志

3. **验证 API Key**
   - 在阿里云 DashScope 控制台验证 API Key
   - 检查免费额度

4. **测试 API 调用**
   - 使用 curl 或 Postman 直接测试 API
   - 验证 API Key 是否有效

---

*文档创建时间：2026-01-28*