178 lines
5.2 KiB
Markdown
178 lines
5.2 KiB
Markdown
# EPEEKit
|
||
|
||
AI 美术资源生成工具集 — 通过对话生成游戏美术资源。
|
||
|
||
## 快速开始
|
||
|
||
### 1. 准备 API Key
|
||
|
||
你需要两个 API Key：
|
||
|
||
- **OpenAI API Key**（或兼容 API）：https://platform.openai.com/api-keys
|
||
- **Replicate API Token**：https://replicate.com/account/api-tokens
|
||
|
||
### 2. 启动后端
|
||
|
||
```bash
|
||
cd art-agent/backend
|
||
|
||
# 创建虚拟环境（推荐）
|
||
python -m venv venv
|
||
venv\Scripts\activate # Windows
|
||
# source venv/bin/activate # macOS/Linux
|
||
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 配置环境变量
|
||
copy .env.example .env
|
||
# 编辑 .env，填入你的 API Key 和模型配置
|
||
|
||
# 启动（--host 0.0.0.0 允许局域网/穿透访问）
|
||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
### 3. 启动前端
|
||
|
||
```bash
|
||
cd art-agent/frontend
|
||
|
||
# 安装依赖（需要 Node.js >= 18）
|
||
npm install
|
||
|
||
# 启动
|
||
npm run dev
|
||
```
|
||
|
||
### 4. 使用
|
||
|
||
打开浏览器访问 http://localhost:3000
|
||
|
||
- 输入文字描述你想要的美术资源
|
||
- 可以上传参考图引导风格
|
||
- 生成的图片可以点击"保存"按钮下载
|
||
- 持续对话进行迭代修改
|
||
|
||
## 访问地址
|
||
|
||
| 场景 | 前端页面 | 后端 API | 后端文档 |
|
||
|------|---------|---------|---------|
|
||
| **本机** | http://localhost:3000 | http://localhost:8000 | http://localhost:8000/docs |
|
||
| **局域网**（同一 WiFi） | `http://<你的IP>:3000` | `http://<你的IP>:8000` | `http://<你的IP>:8000/docs` |
|
||
| **外网**（Cloudflare Tunnel） | `https://xxx.trycloudflare.com`（每次启动不同） | `https://yyy.trycloudflare.com` | — |
|
||
|
||
查看本机局域网 IP：
|
||
|
||
```powershell
|
||
# Windows
|
||
Get-NetIPAddress -AddressFamily IPv4 | Where-Object { $_.InterfaceAlias -eq 'WLAN' }
|
||
|
||
# macOS / Linux
|
||
ifconfig | grep "inet " | grep -v 127.0.0.1
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
所有可配置项都集中在 `backend/.env` 文件中，分为以下几组：
|
||
|
||
| 配置组 | 变量 | 说明 |
|
||
|--------|------|------|
|
||
| **LLM 对话** | `OPENAI_API_KEY` | API 密钥 |
|
||
| | `OPENAI_BASE_URL` | API 基地址，支持任何 OpenAI 兼容 API |
|
||
| | `LLM_MODEL` | 模型名称，如 `gpt-4o-mini`、`deepseek-chat` 等 |
|
||
| | `LLM_MAX_ITERATIONS` | Agent 单轮最大工具调用次数 |
|
||
| **图像生成** | `REPLICATE_API_TOKEN` | Replicate API Token |
|
||
| | `IMAGE_MODEL` | 图像生成模型，如 `black-forest-labs/flux-schnell` |
|
||
| | `IMAGE_ASPECT_RATIO` | 默认宽高比，如 `1:1` |
|
||
| | `IMAGE_OUTPUT_FORMAT` | 输出格式，如 `png` |
|
||
| **网络** | `HTTP_PROXY` / `HTTPS_PROXY` | 代理配置 |
|
||
| **服务** | `PORT` | 后端服务端口 |
|
||
|
||
切换 LLM 供应商只需修改 `OPENAI_BASE_URL` + `OPENAI_API_KEY` + `LLM_MODEL` 三个值。
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
art-agent/
|
||
backend/ # Python FastAPI 后端
|
||
app/
|
||
main.py # 入口
|
||
config.py # 集中配置（读取 .env）
|
||
api/chat.py # 对话 API
|
||
agent/ # Agent Loop 核心
|
||
services/ # AI 服务封装
|
||
frontend/ # Next.js 前端
|
||
src/
|
||
app/ # 页面
|
||
components/ # UI 组件
|
||
lib/ # 工具函数
|
||
docs/ # 文档
|
||
```
|
||
|
||
## 远程访问（外网穿透）
|
||
|
||
通过 Cloudflare Quick Tunnel 免费穿透内网，手机或朋友在任何网络下都能访问，无需买服务器。
|
||
|
||
### 安装 cloudflared
|
||
|
||
```powershell
|
||
# Windows（任选一种）
|
||
winget install Cloudflare.cloudflared
|
||
|
||
# 或手动下载
|
||
# https://github.com/cloudflare/cloudflared/releases/latest
|
||
# 下载 cloudflared-windows-amd64.exe，放到项目目录下即可
|
||
```
|
||
|
||
```bash
|
||
# macOS
|
||
brew install cloudflared
|
||
|
||
# Linux
|
||
# https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/
|
||
```
|
||
|
||
### 一键启动穿透
|
||
|
||
确保前后端服务已经在运行，然后在另一个终端执行：
|
||
|
||
```powershell
|
||
cd art-agent
|
||
.\start-tunnel.ps1
|
||
```
|
||
|
||
脚本会自动：
|
||
1. 为后端和前端各创建一条穿透隧道
|
||
2. 更新 `frontend/.env.local` 中的后端 API 地址为穿透地址
|
||
3. 打印手机可访问的公网 HTTPS 链接
|
||
4. 关闭脚本时（Ctrl+C）自动恢复 `.env.local` 为 localhost
|
||
|
||
> **重要**：穿透启动后需要**重启前端** (`npm run dev`) 才能读取新的 `.env.local`。
|
||
|
||
### 穿透管理
|
||
|
||
| 操作 | 方式 |
|
||
|------|------|
|
||
| **启动** | 运行 `.\start-tunnel.ps1`，等待打印出两条 `trycloudflare.com` 地址 |
|
||
| **停止** | 在脚本窗口按 `Ctrl+C`，或在任务管理器中结束 `cloudflared.exe` 进程 |
|
||
| **查看状态** | 检查日志：`Get-Content $env:TEMP\epeekit-tunnel-backend.log` |
|
||
| **重启** | 先停止再启动，地址会变（Quick Tunnel 每次分配随机域名） |
|
||
|
||
### 注意事项
|
||
|
||
- Quick Tunnel **免费无需账号**，但地址每次启动都会变化
|
||
- 如果 cloudflared 连接超时，可能需要配置代理（Clash 等），在运行脚本前设置：
|
||
```powershell
|
||
$env:HTTP_PROXY = "http://127.0.0.1:7890"
|
||
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
|
||
.\start-tunnel.ps1
|
||
```
|
||
- 电脑关机、休眠或代理断开后隧道会自动失效
|
||
- 停止穿透后，`start-tunnel.ps1` 会自动将 `.env.local` 恢复为 `localhost`；如果手动杀进程，需要自行恢复
|
||
|
||
## 技术栈
|
||
|
||
- 前端：Next.js + TypeScript + Tailwind CSS
|
||
- 后端：Python FastAPI + SSE
|
||
- AI：可配置 LLM（默认 GPT-4o-mini）+ 可配置图像模型（默认 Replicate Flux）
|