232 lines
5.5 KiB
Markdown
232 lines
5.5 KiB
Markdown
# 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助手带来的强大功能吧！🎉**
|
||
|