🧠 ai-service

基于 FastAPI 的多模态推理服务，支持两种运行模式：

• MODE=txt2img：文字生成图片（HunyuanDiT 1.5B）
• MODE=vl：图像理解（Qwen2.5-VL-3B）

---

🚀 快速启动（Docker）

1️⃣ 准备缓存与输出目录

mkdir -p cache/hf outputs

2️⃣ 启动容器

文生图模式（txt2img）

docker run --rm -p 9000:8000 \
  -e MODE=txt2img \
  -e HF_HOME=/app/cache/hf \
  -e HF_HUB_ENABLE_HF_TRANSFER=0 \
  -v "$(pwd)/cache/hf:/app/cache/hf" \
  -v "$(pwd)/outputs:/app/outputs" \
  ai-service:dev-local

图像理解模式（vl）

docker run --rm -p 9000:8000 \
  -e MODE=vl \
  -e HF_HOME=/app/cache/hf \
  -e HF_HUB_ENABLE_HF_TRANSFER=0 \
  -v "$(pwd)/cache/hf:/app/cache/hf" \
  -v "$(pwd)/outputs:/app/outputs" \
  ai-service:dev-local

⚠️ 每次容器只支持一种模式，首次运行会自动从 Hugging Face 下载模型（数 GB）。

---

🧩 健康检查

curl -s http://127.0.0.1:9000/healthz

输出示例：

{"ok": true, "mode": "vl"}

---

🎨 接口示例

1️⃣ 文生图（txt2img）

curl -X POST http://127.0.0.1:9000/txt2img \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a cyberpunk cat"}' \
  -o outputs/cat.png

2️⃣ 图像理解（vl）

curl -X POST http://127.0.0.1:9000/vl \
  -F "image=@example.jpg" \
  -F 'prompt=Describe this image'

---

⚙️ 环境变量说明

变量名	说明	示例值
MODE	运行模式，可选 txt2img 或 vl	txt2img
HF_HOME	Hugging Face 模型缓存路径	/app/cache/hf
HF_HUB_ENABLE_HF_TRANSFER	是否启用 xet 加速通道（建议关闭）	0
USE_FAST	是否启用 fast processor（可选）	1

---

🧱 项目结构

ai-service/
├── src/ai_service/       # 主程序
├── cache/hf/             # 模型缓存
├── outputs/              # 输出结果
├── Dockerfile            # 构建镜像
└── README.md             # 当前文件

---

🐋 构建镜像（如需本地构建）

docker build -t ai-service:dev-local .

---

✅ 状态检查

浏览器打开或命令行执行：

http://127.0.0.1:9000/docs

即可查看 FastAPI 自动生成的接口文档。