WuYongJie/gongxiangp2

Fork 0

chenpei fc17c73df5 docs: 添加AI聊天助手使用指南

2025-10-27 17:50:46 +08:00

5.5 KiB

Raw Blame History

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 获取API密钥。

2. 配置环境变量

在项目根目录的 .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. 启动项目

npm run dev

🚀 使用方法

基本对话

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

发送图片

方式1：点击上传

点击输入框左侧的图片图标
选择要上传的图片
可以继续添加更多图片（最多5张）
输入描述文字（可选）
点击发送

方式2：拖拽上传

打开聊天窗口
直接拖拽图片到聊天区域
松开鼠标完成上传
输入描述文字（可选）
点击发送

方式3：粘贴上传

复制图片到剪贴板
在聊天窗口按 Ctrl+V (Windows) 或 Cmd+V (Mac)
图片自动添加到预览区
输入描述文字（可选）
点击发送

查看和下载AI返回的图片

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

💡 使用技巧

图片编辑示例

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

图片生成示例

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

图片分析示例

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

📊 技术架构

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

数据流程

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

🔧 故障排查

常见问题

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:

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

修改模型参数

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

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

📝 注意事项

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

🆕 更新日志

v1.0.0 (2025-10-27)

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

🔗 相关链接

👥 管理员账号

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

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

5.5 KiB Raw Blame History Unescape Escape