# AI聊天助手使用指南

## 🎯 功能介绍

AI聊天助手是一个集成了Google Gemini AI的智能对话工具，支持文字+图片多模态交互，可以进行图片编辑、内容生成等多种操作。

## 📦 功能特性

### ✅ 图片发送功能
- **点击上传**: 点击图片图标选择文件
- **拖拽上传**: 拖拽图片到聊天窗口
- **粘贴上传**: 直接粘贴剪贴板中的图片（Ctrl/Cmd+V）
- **多图支持**: 一次最多发送5张图片
- **实时预览**: 上传后立即显示预览
- **删除功能**: 可以删除已上传的图片

### ✅ 图片接收功能
- **AI生成图片**: 支持接收AI生成的图片
- **Base64图片**: 自动解析Base64格式
- **InlineData**: 支持Gemini API的inline data格式
- **点击查看**: 点击图片在新窗口查看大图
- **下载图片**: Hover图片显示下载按钮

### ✅ 对话功能
- **流式对话**: 支持连续多轮对话
- **上下文记忆**: 保留对话历史和图片信息
- **实时响应**: 快速的AI响应
- **多模态理解**: 同时理解文字和图片

## ⚙️ 配置步骤

### 1. 获取Gemini API Key

访问 [Google AI Studio](https://aistudio.google.com/app/apikey) 获取API密钥。

### 2. 配置环境变量

在项目根目录的 `.env` 文件中添加：

```env
# Gemini AI Configuration
GEMINI_API_KEY=your_gemini_api_key_here
GEMINI_API_BASE_URL=https://generativelanguage.googleapis.com/v1beta
GEMINI_MODEL=gemini-2.0-flash-exp
```

**参数说明：**
- `GEMINI_API_KEY`: 你的Gemini API密钥（必填）
- `GEMINI_API_BASE_URL`: API基础URL（可选，默认值如上）
- `GEMINI_MODEL`: 使用的模型名称（可选，默认：gemini-2.0-flash-exp）

**可用模型：**
- `gemini-2.0-flash-exp` - 最新实验版（推荐）
- `gemini-1.5-pro` - 专业版
- `gemini-1.5-flash` - 快速版

### 3. 启动项目

```bash
npm run dev
```

## 🚀 使用方法

### 基本对话

1. 点击右下角的紫色AI助手按钮
2. 在输入框输入文字
3. 按Enter发送（Shift+Enter换行）

### 发送图片

**方式1：点击上传**
1. 点击输入框左侧的图片图标
2. 选择要上传的图片
3. 可以继续添加更多图片（最多5张）
4. 输入描述文字（可选）
5. 点击发送

**方式2：拖拽上传**
1. 打开聊天窗口
2. 直接拖拽图片到聊天区域
3. 松开鼠标完成上传
4. 输入描述文字（可选）
5. 点击发送

**方式3：粘贴上传**
1. 复制图片到剪贴板
2. 在聊天窗口按 Ctrl+V (Windows) 或 Cmd+V (Mac)
3. 图片自动添加到预览区
4. 输入描述文字（可选）
5. 点击发送

### 查看和下载AI返回的图片

1. AI返回的图片会显示在消息气泡中
2. **点击图片** - 在新窗口查看大图
3. **Hover图片** - 显示下载按钮
4. **点击下载** - 保存图片到本地

## 💡 使用技巧

### 图片编辑示例

```
"请帮我把这张图片的背景改成蓝色"
"给这张图片添加一个卡通滤镜"
"帮我去除图片中的文字"
"把这张图片转换成黑白的"
```

### 图片生成示例

```
"生成一张日落海滩的图片"
"创建一个可爱的卡通猫咪"
"设计一个科技感的logo"
```

### 图片分析示例

```
"这张图片里有什么？"
"帮我识别图片中的文字"
"分析这张图片的构图"
"这是什么品种的狗？"
```

## 📊 技术架构

```
Frontend (AIChatWidget)
    ↓
API Route (/api/ai-chat)
    ↓
Gemini AI API
```

### 数据流程

1. **图片上传** → Base64编码 → 前端预览
2. **发送消息** → 构建对话历史 → 调用API
3. **API处理** → 转换格式 → 调用Gemini
4. **接收响应** → 解析图片/文字 → 前端显示

## 🔧 故障排查

### 常见问题

**Q: 发送消息时提示"未授权"**
A: 请确保已登录系统

**Q: 提示"Gemini API未配置"**
A: 检查.env文件中的GEMINI_API_KEY是否正确设置

**Q: 图片上传后无法发送**
A: 检查图片大小，建议单张图片不超过4MB

**Q: AI响应很慢**
A: 可能是网络问题或API限制，请稍后重试

**Q: 图片无法显示**
A: 检查浏览器控制台是否有错误信息

### API错误代码

- **401**: API密钥无效或过期
- **429**: 请求频率过高，请稍后重试
- **500**: 服务器错误，请联系管理员

## 🎨 自定义配置

### 修改最大图片数量

编辑 `components/AIChatWidget.tsx`:

```typescript
// 将5改为你想要的数量
setImages(prev => [...prev, ...files].slice(0, 5))
```

### 修改模型参数

编辑 `app/api/ai-chat/route.ts`:

```typescript
generationConfig: {
  temperature: 1,        // 创造性（0-2）
  topK: 40,             // 采样范围
  topP: 0.95,           // 核采样
  maxOutputTokens: 8192 // 最大输出长度
}
```

## 📝 注意事项

1. **API配额**: Gemini API有使用限制，请合理使用
2. **图片大小**: 建议单张图片不超过4MB
3. **隐私安全**: 不要上传敏感或私人图片
4. **网络要求**: 需要稳定的网络连接
5. **浏览器兼容**: 推荐使用Chrome、Firefox、Edge等现代浏览器

## 🆕 更新日志

### v1.0.0 (2025-10-27)
- ✅ 初始版本发布
- ✅ 支持文字+图片多模态对话
- ✅ 集成Gemini AI API
- ✅ 支持拖拽、粘贴上传图片
- ✅ 支持图片查看和下载
- ✅ 对话历史管理
- ✅ 黑夜模式支持

## 🔗 相关链接

- [Gemini API文档](https://ai.google.dev/docs)
- [项目GitHub](https://github.com/your-repo)
- [问题反馈](https://github.com/your-repo/issues)

## 👥 管理员账号

```
用户名: admin
邮箱: admin@youyidian3d.com
密码: admin123456
```

---

**享受AI助手带来的强大功能吧！🎉**