Skip to content
BranchesTags

Repository files navigation

AI Director Workbench（AI 导演工作台）

基于 FastAPI + Celery + SQLite 的 AI 角色扮演与图像生成工作台。前端无框架，原生 JavaScript + DOM 操作；后端 SQLAlchemy 2.0 async + Celery 异步任务队列。

主要解决的痛点

  • 角色一致性差：AI 短视频制作流行，但生成过程中角色形象的随机性比较大。
  • 手工调整易出错：更换故事内容后，分镜图提示词需要多处调整，手工微调拼接效率低。

功能特性

  • 多角色 AI 对话：基于智能体配置（AgentConfig）驱动不同风格的 AI 角色
  • 图像生成：集成 grsai 兼容端点，支持参考图、多比例、积分体系
  • 世界观系统：角色按世界观分组，支持系统预设与用户自建
  • 起首语配置：图片/视频生成的前置 prompt 模板
  • 管理后台：SQLAdmin 驱动的完整管理界面（/admin）
  • 用户体系：JWT + Refresh Token，配额管理，邀请码
  • 异步任务：Celery Worker 处理图像生成，Beat 定时清理，Flower 监控
  • 审核系统：角色形象定制审核流程，图片审核智能体

界面预览

主页

主页

分镜图示例

分镜图示例

角色管理

角色管理

操作演示

观看 B站操作演示视频

技术栈

层 技术
后端 FastAPI + SQLAlchemy 2.0 async + Pydantic v2
任务队列 Celery + Redis
数据库 SQLite (aiosqlite)
管理后台 SQLAdmin 0.22.0
前端 原生 JavaScript + DOM（无框架）
容器 Docker / Podman Compose

技术架构

技术架构

快速开始（Docker 部署）

1. 克隆仓库

git clone https://github.com/cckais/ai-director-workbench.git
cd ai-director-workbench

2. 配置环境变量

cp .env.example .env

编辑 .env，必须填写以下项：

# 安全密钥（必须修改，否则服务拒绝启动）
JWT_SECRET_KEY=<至少32位随机字符串>
SESSION_SECRET_KEY=<至少32位随机字符串>

# 超级管理员（首次启动自动创建）
SUPER_ADMIN_EMAIL=your-email@example.com
SUPER_ADMIN_PASSWORD=<至少8位，含字母和数字，不能包含"admin">

# CORS（你的访问地址，多个用逗号分隔）
CORS_ALLOWED_ORIGINS=http://localhost:8765

# API 密钥池（逗号分隔，至少一个）
API_KEY_POOL=your-deepseek-api-key
IMAGE_API_KEY_POOL=your-grsai-api-key

生成密钥的快捷命令：

python -c "import secrets; print(secrets.token_urlsafe(48))"

最小可用配置示例

只想体验 AI 对话功能，可以只配置 DeepSeek 官方 API：

# 安全密钥
JWT_SECRET_KEY=<运行上面命令生成>
SESSION_SECRET_KEY=<运行上面命令生成>

# 超级管理员
SUPER_ADMIN_EMAIL=your-email@example.com
SUPER_ADMIN_PASSWORD=YourPassword123

# CORS
CORS_ALLOWED_ORIGINS=http://localhost:8765

# 只配置 DeepSeek 官方 API（对话功能）
API_KEY_POOL=sk-xxxxxxxxxxxxxxxxxxxxxxxx
# IMAGE_API_KEY_POOL 可以先不配置，图像生成功能暂不可用

说明：IMAGE_API_KEY_POOL 为空时，图像生成按钮会显示"需配置 API"提示，但不影响对话功能。

3. 构建并启动

docker compose up -d --build

服务列表：

服务 容器端口 宿主端口 用途
web 8000 8765 FastAPI 主服务
worker - - Celery 图像生成
beat - - Celery 定时清理
flower 5555 8766（仅 127.0.0.1） 任务监控
redis 6379 - 消息队列

4. 访问

  • 主站：http://localhost:8765
  • 管理后台：http://localhost:8765/admin（用 .env 中配置的超管账号登录）
  • Flower 监控：ssh -L 8766:localhost:8766 user@server，然后访问 http://localhost:8766

种子数据导入

首次启动容器时，若 backend/seed/*.json 不为空，会自动导入智能体/世界观/起首语配置（受 AUTO_IMPORT_SEED=true 控制）。

  • 默认 3 个 JSON 均为空数组 []
  • 字段说明见 backend/seed/README.md
  • 手动导入：docker compose exec web python -m scripts.import_seed
  • 覆盖导入：docker compose exec web python -m scripts.import_seed --force

角色形象配置

角色形象（Character）用于 AI 导演工作台的图片生成流程，首次部署后需要手动配置至少一个角色才能正常使用。

为什么角色没有预置数据？

角色形象由 4 张图片（头像、设定图、多配色图、体型对比图）+ 提示词 JSON 组成，涉及图片素材，不适合用纯文本 seed 预置。请按以下步骤手动配置。

配置步骤

  1. 登录管理后台：http://localhost:8765/admin
  2. 进入「内容运营 → 角色管理」
  3. 点击「创建」，填写以下内容：
    • 名称：角色名（如"示例角色"）
    • 描述：角色简介
    • 默认提示词：JSON 格式，包含 globalSetting、roleCore、extraDesc 三部分
    • 所属世界观：可选，留空表示通用角色
    • 头像 / 设定图 / 多配色图 / 体型对比图：上传对应图片
    • 是否系统预设：建议勾选（系统预设角色所有用户可见）
  4. 保存即可

提示词 JSON 示例

{
  "globalSetting": "画面风格设定...",
  "roleCore": "角色核心外观描述...",
  "extraDesc": "补充细节..."
}

提示词的具体写法请参考项目文档或自行摸索，这里仅提供结构示例。

环境变量完整说明

见 .env.example，每个变量都有内联注释。

关键变量：

变量 必填 说明
JWT_SECRET_KEY ✅ JWT 签名密钥，≥32 字节
SESSION_SECRET_KEY ✅ Session Cookie 签名密钥，≥32 字节
SUPER_ADMIN_EMAIL ✅ 超管邮箱（不能含 "admin"）
SUPER_ADMIN_PASSWORD ✅ 超管密码（≥8 位，含字母数字，不能含 "admin"）
CORS_ALLOWED_ORIGINS ✅ 允许的前端来源（逗号分隔）
API_KEY_POOL ✅ DeepSeek/OpenAI 兼容 API 密钥池
IMAGE_API_KEY_POOL ✅ grsai 图像生成 API 密钥池
OPENAI_COMPATIBLE_ENDPOINT ⚠️ 你的 OpenAI 兼容端点，留空则不启用
GRSAI_ENDPOINT ⚠️ 你的 grsai 兼容端点，留空则不启用
APP_MASTER_KEY 可选 API Key 加密主密钥（Fernet），留空则从 JWT_SECRET_KEY 派生
AUTO_IMPORT_SEED 可选 首次启动是否自动导入种子数据，默认 true

生产部署

部署到阿里云 ECS / 其他云服务器，见 docs/deploy-aliyun.md。

子项目集成

本项目有 5 个配套子项目，可独立部署后集成到主站菜单：

子项目 仓库 集成方式
纯前端版本 ai-director-frontend 独立运行的纯前端项目，无需后端服务，适合轻量级 Prompt 编辑与 AI 对话场景
视频编辑器 video-editor 独立部署后通过 Nginx 反代挂到 /editor/ 路径，主站前端菜单按需添加跳转入口
图片切割工具 image-cutter 独立部署后通过 Nginx 反代挂到 /cutter/ 路径，主站前端菜单按需添加跳转入口
评审问题追踪 code-review-issues 纯文档项目，复制到主站 docs/code-review-issues/ 即可
世界观定制协议 worldview-protocol 纯文档项目，复制到主站 docs/worldview-protocol/ 即可

开源版主站默认不显示子项目入口，按需在 frontend/index.html 中启用菜单项。

项目结构

.
├── backend/
│   ├── app/
│   │   ├── api/            # FastAPI 路由
│   │   ├── models/         # SQLAlchemy 模型
│   │   ├── schemas/        # Pydantic schema
│   │   ├── services/       # 业务服务
│   │   ├── middleware/     # 中间件
│   │   ├── worker_tasks/   # Celery 任务
│   │   ├── admin.py        # SQLAdmin 配置
│   │   ├── config.py       # 配置（pydantic-settings）
│   │   ├── database.py     # 数据库引擎 + 迁移
│   │   └── main.py         # FastAPI 入口
│   ├── scripts/
│   │   ├── import_seed.py  # 种子数据导入
│   │   └── export_seed.py  # 种子数据导出
│   ├── seed/               # 种子数据 JSON
│   ├── templates/sqladmin/ # SQLAdmin 模板覆盖
│   ├── requirements.txt
│   └── .env.example
├── frontend/
│   ├── index.html
│   ├── css/
│   └── js/
├── docs/                   # 部署与集成文档
├── Dockerfile
├── docker-compose.yml
├── docker-entrypoint.sh
└── .env.example

开发

本地裸机开发（不用 Docker）

# 后端
cd backend
pip install -r requirements.txt
cp .env.example .env  # 填写密钥
uvicorn app.main:app --reload --port 8000

# 前端：直接用后端 StaticFiles 提供，无需单独启动
# 访问 http://localhost:8000

# Celery Worker（另一个终端）
celery -A app.celery_app.celery_app worker --loglevel=info -Q image,cleanup

# Celery Beat（另一个终端）
celery -A app.celery_app.celery_app beat --loglevel=info

需要本地 Redis：docker run -d -p 6379:6379 redis:7-alpine

License

MIT

About

基于 FastAPI + Celery + SQLite 的 AI 角色扮演与图像生成工作台

Topics

aiceleryfastapiimage-generationsqladminsqlalchemy

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages