README.md

metadata

title: FlorenceForge Agentic Visual Reasoning
emoji: 🎨
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false

FlorenceForge Agentic WebUI

独立 Gradio 前端，支持 外部后端模式 和 嵌入式模式 两种运行方式。可部署到 Hugging Face Spaces。

---

快速开始

方式 1：外部后端模式（推荐，本地开发）

# 终端 1: 启动 FlorenceForge 后端
florence_forge_cli serve --model microsoft/Florence-2-base --port 8000 --agentic

# 终端 2: 启动 WebUI
python app.py
# 浏览器访问: http://localhost:7860

方式 2：嵌入式模式（自包含运行）

# 直接加载模型，无需外部后端
FLORENCE_MODE=embedded python app.py --model microsoft/Florence-2-base --device cpu

方式 3：一键脚本

chmod +x start.sh
./start.sh

---

Hugging Face Spaces 部署

选项 A：Docker 部署（推荐）

1. 在 huggingface.co 创建新 Space，选择 Docker SDK
2. 将本仓库代码推送到 Space 的 git 仓库
3. 设置环境变量（在 Space 的 Settings → Variables 中）：
   • FLORENCE_MODEL: microsoft/Florence-2-base（或 microsoft/Florence-2-large）
   • FLORENCE_DEVICE: auto（Spaces 免费版使用 CPU）
4. Spaces 自动构建并部署

选项 B：Gradio SDK 部署

1. 在 huggingface.co 创建新 Space，选择 Gradio SDK
2. 将本仓库代码推送到 Space 的 git 仓库
3. 确保 requirements.txt 包含所有依赖
4. Spaces 自动运行 app.py

⚠️ 注意：Florence-2 模型较大（base ~500MB, large ~1.7GB），首次部署时需要下载模型，可能耗时较长。Spaces 免费版使用 CPU 推理，速度较慢。

---

架构

┌─────────────────────────────────────────────────────────────┐
│                    Hugging Face Spaces                       │
│  ┌────────────────────┐                                     │
│  │  Gradio WebUI      │                                     │
│  │  /app.py           │                                     │
│  │  (port 7860)       │                                     │
│  └────────────────────┘                                     │
│           │                                                  │
│  ┌────────┴────────┐    ┌──────────────────────────────┐  │
│  │  Embedded Mode    │    │  External Backend Mode        │  │
│  │  (直接加载模型)    │    │  (HTTP API 连接)              │  │
│  │                   │    │                               │  │
│  │  Florence-2 Model │    │  FlorenceForge Backend        │  │
│  │  + AgenticOrchestrator│  (FastAPI)                    │  │
│  │                   │    │  (可以是远程服务器)            │  │
│  └───────────────────┘    └───────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

---

配置

环境变量

变量	默认值	说明
FLORENCE_BACKEND_URL	http://127.0.0.1:8000	外部后端地址（外部模式）
FLORENCE_MODEL	microsoft/Florence-2-base	模型名称（嵌入式模式）
FLORENCE_DEVICE	auto	推理设备（嵌入式模式）
FLORENCE_MODE	external	embedded 或 external
FLORENCE_WEBUI_HOST	0.0.0.0	WebUI 监听地址
FLORENCE_WEBUI_PORT	7860	WebUI 监听端口
FLORENCE_WEBUI_SHARE	false	Gradio 公共链接

命令行参数

python app.py --help

--backend-url URL       外部后端地址
--model MODEL, -m MODEL 模型名称（嵌入式模式）
--device DEVICE, -d DEVICE 推理设备
--host HOST             监听地址
--port PORT, -p PORT    监听端口
--share                 生成公共链接
--config PATH           YAML 配置文件
--embedded              强制嵌入式模式

---

文件结构

florence-forge-webui/
├── app.py              ← Gradio 应用入口
├── requirements.txt    ← Python 依赖
├── Dockerfile        ← HF Spaces Docker 部署
├── config.yaml       ← 配置示例
├── start.sh          ← 一键启动脚本
└── README.md         ← 本文档

---

开发

# 安装依赖
pip install -r requirements.txt

# 外部后端模式开发
python app.py --backend-url http://127.0.0.1:8000

# 嵌入式模式开发（需要 GPU/CPU + 模型）
FLORENCE_MODE=embedded python app.py --model microsoft/Florence-2-base --device cpu

# 使用配置文件
python app.py --config config.yaml

---

许可证

MIT