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

# FlorenceForge Agentic WebUI

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

---

## 快速开始

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

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

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

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

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

### 方式 3：一键脚本

```bash
chmod +x start.sh
./start.sh
```

---

## Hugging Face Spaces 部署

### 选项 A：Docker 部署（推荐）

1. 在 [huggingface.co](https://huggingface.co/spaces) 创建新 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](https://huggingface.co/spaces) 创建新 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 公共链接 |

### 命令行参数

```bash
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         ← 本文档
```

---

## 开发

```bash
# 安装依赖
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