TikZ 代码自动生成系统

基于大模型的 TikZ 代码自动生成系统，支持用户上传草图和自然语言描述，自动生成高质量的 TikZ 代码和 PDF 文件。

功能特性 • 快速开始 • 部署指南 • API 文档

---

📋 目录

• 功能特性
• 系统架构
• 快速开始
• 环境配置
• 部署指南
• 使用说明
• API 文档
• 项目结构
• 故障排除
• 开发指南

---

🌟 功能特性

核心功能

• 🎨 智能图形识别：上传手绘草图，AI 自动识别图形结构
• 💬 自然语言交互：使用自然语言描述图形需求
• 🔧 TikZ 代码生成：自动生成高质量、可编辑的 TikZ 代码
• 📄 PDF 实时预览：即时生成 PDF 文件并在线预览
• 👥 用户管理系统：完整的用户注册、登录、认证机制
• 📊 项目管理：支持多项目管理和历史记录查询
• 💡 反馈系统：用户可对生成结果进行评价和反馈

技术特点

• 🚀 高性能：基于 Flask 框架，支持并发请求
• 🔐 安全可靠：JWT 令牌认证，密码加密存储
• 💾 轻量级数据库：SQLite 数据库，无需复杂配置
• 🎯 RESTful API：标准化 API 接口设计
• 📱 响应式设计：现代化 Web 界面，支持多设备访问
• 🔄 可扩展架构：模块化设计，易于扩展和维护

---

🏗️ 系统架构

┌─────────────────────────────────────────────────────────┐
│                      前端界面层                          │
│  (HTML/CSS/JavaScript - 响应式设计)                      │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                    Flask Web 服务层                      │
│  • 路由管理  • 请求处理  • 响应封装                      │
└─────────────────────────────────────────────────────────┘
                          ↓
┌──────────────┬──────────────┬──────────────┬───────────┐
│  认证模块    │  项目管理    │  文件处理    │  反馈系统 │
│  (auth.py)   │  (main.py)   │  (main.py)   │ (main.py) │
└──────────────┴──────────────┴──────────────┴───────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                   TikZ 生成引擎                          │
│  • 大模型调用  • 代码生成  • LaTeX 编译                  │
│  (tikz_generator.py)                                    │
└─────────────────────────────────────────────────────────┘
                          ↓
┌──────────────┬──────────────┬──────────────────────────┐
│  数据库层    │  文件存储    │  外部服务                │
│  (SQLite)    │  (本地磁盘)  │  (OpenAI API)            │
└──────────────┴──────────────┴──────────────────────────┘

---

🚀 快速开始

系统要求

• Python 3.6+ （必需）
• pip （Python 包管理器）
• LaTeX 环境 （可选，用于 PDF 生成）
  • macOS: brew install --cask mactex
  • Ubuntu/Debian: sudo apt-get install texlive-latex-base texlive-latex-extra
  • CentOS/RHEL: sudo yum install texlive-latex

一键安装

# 克隆项目（如果从 Git 仓库）
git clone <repository-url>
cd ai_agent_demo

# 运行安装脚本
chmod +x install.sh
./install.sh

手动安装

# 1. 进入项目目录
cd ai_agent_demo

# 2. 安装 Python 依赖
pip3 install -r requirements.txt

# 3. 验证安装
python3 verify.py

# 4. 启动服务
python3 main.py

访问系统

启动成功后，在浏览器中访问：

http://localhost:8000

---

⚙️ 环境配置

配置文件

系统配置位于 config.py，支持通过环境变量覆盖默认配置。

环境变量

创建 .env 文件或设置系统环境变量：

# 应用配置
APP_DEBUG=false                          # 调试模式（生产环境设为 false）
SECRET_KEY=your-secret-key-here          # JWT 密钥（必须修改）

# 数据库配置
DATABASE_URL=sqlite:///./tikz_generator.db

# 文件存储配置
UPLOAD_DIR=/path/to/uploads              # 上传文件目录
GENERATED_DIR=/path/to/generated         # 生成文件目录
MAX_FILE_SIZE=10485760                   # 最大文件大小（字节）

# 大模型 API 配置
OPENAI_API_KEY=your-api-key              # OpenAI API 密钥
OPENAI_BASE_URL=https://api.openai.com   # API 基础 URL
DEFAULT_MODEL=gpt-4-vision-preview       # 默认模型

# JWT 配置
JWT_ALGORITHM=HS256                      # JWT 算法
ACCESS_TOKEN_EXPIRE_MINUTES=30           # Token 过期时间（分钟）

# LaTeX 配置
LATEX_TIMEOUT=30                         # LaTeX 编译超时时间（秒）

配置示例

开发环境：

export APP_DEBUG=true
export SECRET_KEY=dev-secret-key
export OPENAI_API_KEY=your-dev-key
python3 main.py

生产环境：

export APP_DEBUG=false
export SECRET_KEY=$(openssl rand -hex 32)
export OPENAI_API_KEY=your-prod-key
export DATABASE_URL=postgresql://user:pass@localhost/dbname
gunicorn -w 4 -b 0.0.0.0:8000 main:app

---

🚢 部署指南

开发环境部署

# 直接运行
python3 main.py

生产环境部署

使用 Gunicorn（推荐）

# 安装 Gunicorn
pip3 install gunicorn

# 启动服务（4 个工作进程）
gunicorn -w 4 -b 0.0.0.0:8000 main:app

# 后台运行
nohup gunicorn -w 4 -b 0.0.0.0:8000 main:app > gunicorn.log 2>&1 &

使用 Nginx 反向代理

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /uploads {
        alias /path/to/ai_agent_demo/uploads;
    }

    location /generated {
        alias /path/to/ai_agent_demo/generated;
    }
}

使用 Systemd 服务

创建 /etc/systemd/system/tikz-generator.service：

[Unit]
Description=TikZ Generator Service
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/path/to/ai_agent_demo
Environment="PATH=/usr/bin:/usr/local/bin"
Environment="OPENAI_API_KEY=your-api-key"
Environment="SECRET_KEY=your-secret-key"
ExecStart=/usr/bin/gunicorn -w 4 -b 0.0.0.0:8000 main:app
Restart=always

[Install]
WantedBy=multi-user.target

启动服务：

sudo systemctl daemon-reload
sudo systemctl start tikz-generator
sudo systemctl enable tikz-generator
sudo systemctl status tikz-generator

Docker 部署

创建 Dockerfile：

FROM python:3.9-slim

# 安装 LaTeX
RUN apt-get update && apt-get install -y \
    texlive-latex-base \
    texlive-latex-extra \
    && rm -rf /var/lib/apt/lists/*

# 设置工作目录
WORKDIR /app

# 复制依赖文件
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY . .

# 暴露端口
EXPOSE 8000

# 启动命令
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8000", "main:app"]

构建和运行：

# 构建镜像
docker build -t tikz-generator .

# 运行容器
docker run -d \
  -p 8000:8000 \
  -e OPENAI_API_KEY=your-api-key \
  -e SECRET_KEY=your-secret-key \
  -v $(pwd)/uploads:/app/uploads \
  -v $(pwd)/generated:/app/generated \
  -v $(pwd)/tikz_generator.db:/app/tikz_generator.db \
  --name tikz-generator \
  tikz-generator

---

📖 使用说明

1. 用户注册与登录

注册新账户

1. 访问首页，点击「注册」按钮
2. 填写用户名和密码（密码至少 6 位）
3. 点击「注册」完成账户创建

登录系统

1. 在登录页面输入用户名和密码
2. 点击「登录」进入系统
3. 系统会自动保存登录状态（Token）

2. 创建 TikZ 项目

基本流程

1. 点击「创建新项目」
2. 填写项目信息：
   • 项目标题（必填）
   • 自然语言描述（必填）
   • 上传草图图片（可选）
3. 提交创建：系统自动生成 TikZ 代码和 PDF
4. 查看结果：在项目详情页查看生成的代码和预览

最佳实践

描述建议：

• ✅ 清晰描述图形类型（流程图、树状图、网络图等）
• ✅ 说明节点数量和连接关系
• ✅ 指定颜色、样式等特殊要求
• ❌ 避免模糊或过于复杂的描述

示例描述：

创建一个包含 5 个节点的流程图：
- 起始节点（绿色圆形）
- 3 个处理节点（蓝色矩形）
- 结束节点（红色圆形）
节点之间用箭头连接，从左到右排列

3. 查看和管理项目

项目列表

• 在「我的项目」页面查看所有项目
• 支持按创建时间排序
• 点击项目卡片进入详情页

项目详情

• TikZ 代码：可复制、编辑
• PDF 预览：在线查看生成的 PDF
• 原始图片：查看上传的草图
• 项目信息：标题、描述、创建时间

4. 反馈系统

对生成结果不满意？提交反馈帮助改进：

1. 在项目详情页点击「提交反馈」
2. 选择评分（1-5 星）
3. 填写反馈内容
4. 提交反馈

---

📡 API 文档

认证接口

用户注册

POST /api/register
Content-Type: application/json

{
  "username": "user123",
  "password": "password123"
}

响应：

{
  "message": "注册成功",
  "user_id": 1
}

用户登录

POST /api/login
Content-Type: application/json

{
  "username": "user123",
  "password": "password123"
}

响应：

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

项目接口

获取项目列表

GET /api/projects
Authorization: Bearer <token>

响应：

{
  "projects": [
    {
      "id": 1,
      "title": "流程图示例",
      "created_at": "2025-10-10T12:00:00",
      "has_pdf": true
    }
  ]
}

创建新项目

POST /api/projects
Authorization: Bearer <token>
Content-Type: multipart/form-data

title: 流程图示例
natural_desc: 创建一个简单的流程图
file: (binary)

响应：

{
  "message": "项目创建成功",
  "project_id": 1,
  "tikz_code": "\\begin{tikzpicture}...",
  "pdf_generated": true
}

获取项目详情

GET /api/projects/{id}
Authorization: Bearer <token>

响应：

{
  "id": 1,
  "title": "流程图示例",
  "natural_desc": "创建一个简单的流程图",
  "tikz_code": "\\begin{tikzpicture}...",
  "image_path": "uploads/xxx.png",
  "pdf_path": "generated/xxx.pdf",
  "created_at": "2025-10-10T12:00:00"
}

提交项目反馈

POST /api/projects/{id}/feedback
Authorization: Bearer <token>
Content-Type: application/json

{
  "rating": 5,
  "comment": "生成效果很好！"
}

响应：

{
  "message": "反馈提交成功"
}

文件接口

访问上传文件

GET /uploads/{filename}

访问生成文件

GET /generated/{filename}

---

📁 项目结构

ai_agent_demo/
├── main.py                 # Flask 应用主文件
├── config.py               # 配置文件
├── database.py             # 数据库模型和操作
├── auth.py                 # 认证和授权模块
├── tikz_generator.py       # TikZ 代码生成引擎
├── requirements.txt        # Python 依赖列表
├── install.sh              # 安装脚本
├── verify.py               # 环境验证脚本
├── README.md               # 项目文档
├── DEPLOYMENT.md           # 部署文档
│
├── templates/              # HTML 模板
│   ├── index.html          # 首页
│   ├── login.html          # 登录页
│   ├── register.html       # 注册页
│   ├── create.html         # 创建项目页
│   ├── projects.html       # 项目列表页
│   └── project_detail.html # 项目详情页
│
├── static/                 # 静态资源（CSS/JS/图片）
│
├── uploads/                # 用户上传文件存储
├── generated/              # 生成的 PDF 文件存储
├── tikz_generator.db       # SQLite 数据库文件
│
└── __pycache__/            # Python 缓存文件

核心模块说明

模块	功能	主要类/函数
main.py	Flask 应用和路由	app, 路由处理函数
config.py	配置管理	配置常量
database.py	数据库操作	User, Project, Feedback
auth.py	用户认证	create_token(), verify_token()
tikz_generator.py	TikZ 生成	generate_tikz_code(), generate_pdf()

---

🐛 故障排除

常见问题

1. 端口被占用

问题：Address already in use

解决方案：

# 查看端口占用
lsof -i :8000

# 杀死占用进程
kill -9 <PID>

# 或使用其他端口
python3 main.py --port 8001

2. LaTeX 未安装

问题：pdflatex not found

解决方案：

# macOS
brew install --cask mactex

# Ubuntu/Debian
sudo apt-get install texlive-latex-base texlive-latex-extra

# CentOS/RHEL
sudo yum install texlive-latex

3. 依赖安装失败

问题：pip install 报错

解决方案：

# 升级 pip
pip3 install --upgrade pip

# 使用国内镜像
pip3 install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 使用虚拟环境
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

4. 文件上传失败

问题：FileNotFoundError 或 Permission denied

解决方案：

# 检查目录权限
ls -la uploads/ generated/

# 修复权限
chmod 755 uploads/ generated/
chown -R $USER:$USER uploads/ generated/

# 确保目录存在
mkdir -p uploads generated

5. 数据库错误

问题：database is locked 或 no such table

解决方案：

# 删除旧数据库（注意：会丢失数据）
rm tikz_generator.db

# 重启应用（会自动创建新数据库）
python3 main.py

6. API 调用失败

问题：OpenAI API error

解决方案：

# 检查 API 密钥
echo $OPENAI_API_KEY

# 设置正确的 API 密钥
export OPENAI_API_KEY=your-api-key

# 检查网络连接
curl -I https://api.openai.com

# 查看详细日志
export APP_DEBUG=true
python3 main.py

日志查看

系统日志包含详细的运行信息：

# 查看实时日志
tail -f gunicorn.log

# 搜索错误日志
grep ERROR gunicorn.log

# 查看最近 100 行
tail -n 100 gunicorn.log

性能优化

数据库优化

# 在 database.py 中添加索引
CREATE INDEX idx_project_user ON projects(user_id);
CREATE INDEX idx_project_created ON projects(created_at);

文件缓存

# 在 main.py 中添加缓存头
@app.route('/uploads/<filename>')
def uploaded_file(filename):
    response = send_file(...)
    response.cache_control.max_age = 3600  # 1 小时缓存
    return response

---

👨‍💻 开发指南

开发环境设置

# 1. 克隆项目
git clone <repository-url>
cd ai_agent_demo

# 2. 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 3. 安装开发依赖
pip install -r requirements.txt
pip install pytest black flake8  # 开发工具

# 4. 启动开发服务器
export APP_DEBUG=true
python3 main.py

代码规范

# 代码格式化
black *.py

# 代码检查
flake8 *.py

# 运行测试
pytest

添加新功能

1. 创建新路由：在 main.py 中添加路由处理函数
2. 更新数据库：在 database.py 中添加新模型或字段
3. 添加模板：在 templates/ 中创建新的 HTML 模板
4. 更新文档：在 README 中记录新功能

调试技巧

# 启用调试模式
app.run(debug=True)

# 添加日志
import logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)
logger.debug("调试信息")

# 使用断点
import pdb; pdb.set_trace()

贡献代码

1. Fork 项目
2. 创建功能分支：git checkout -b feature/new-feature
3. 提交更改：git commit -am 'Add new feature'
4. 推送分支：git push origin feature/new-feature
5. 创建 Pull Request

---

📊 性能指标

• 响应时间：< 2s（TikZ 代码生成）
• 并发支持：100+ 并发用户（使用 Gunicorn）
• 文件大小限制：10MB（可配置）
• 数据库：SQLite（支持切换到 PostgreSQL/MySQL）

---

🔒 安全建议

生产环境安全清单

• 修改默认 SECRET_KEY
• 使用 HTTPS（配置 SSL 证书）
• 限制文件上传大小和类型
• 启用 CORS 保护
• 配置防火墙规则
• 定期备份数据库
• 使用环境变量存储敏感信息
• 启用日志审计
• 限制 API 请求频率
• 定期更新依赖包

---

📝 更新日志

v1.0.0 (2025-10-10)

• ✨ 初始版本发布
• ✅ 完整的用户认证系统
• ✅ TikZ 代码自动生成
• ✅ PDF 文件生成和预览
• ✅ 项目管理功能
• ✅ 反馈系统

---

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

---

🆘 获取帮助

文档资源

• Flask 官方文档
• TikZ 官方文档
• SQLite 文档

联系方式

• 问题反馈：提交 GitHub Issue
• 功能建议：创建 Feature Request
• 安全问题：发送邮件至 security@example.com

---

🙏 致谢

感谢以下开源项目：

• Flask - Web 框架
• SQLite - 数据库
• TikZ - LaTeX 绘图包
• OpenAI - 大模型 API

---

⬆ 返回顶部

Made with ❤️ by TikZ Generator Team