# Florence-2

Мощная визуальная модель Microsoft для генерации подписей, детекции, сегментации и не только.

{% hint style="success" %}
Все примеры можно запускать на GPU-серверах, арендуемых через [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

{% hint style="info" %}
Все примеры в этом руководстве можно запустить на GPU-серверах, арендуемых через [CLORE.AI Marketplace](https://clore.ai/marketplace) маркетплейс.
{% endhint %}

## Аренда на CLORE.AI

1. Посетите [CLORE.AI Marketplace](https://clore.ai/marketplace)
2. Отфильтруйте по типу GPU, объему VRAM и цене
3. Выберите **On-Demand** (фиксированная ставка) или **Spot** (цена по ставке)
4. Настройте ваш заказ:
   * Выберите Docker-образ
   * Установите порты (TCP для SSH, HTTP для веб-интерфейсов)
   * Добавьте переменные окружения при необходимости
   * Введите команду запуска
5. Выберите способ оплаты: **CLORE**, **BTC**, или **USDT/USDC**
6. Создайте заказ и дождитесь развертывания

### Доступ к вашему серверу

* Найдите данные для подключения в **Моих заказах**
* Веб-интерфейсы: используйте URL HTTP-порта
* SSH: `ssh -p <port> root@<proxy-address>`

## Что такое Florence-2?

Florence-2 от Microsoft — это фундаментальная визуальная модель, которая выполняет:

* Генерация подписей к изображению (краткие и подробные)
* Обнаружение объектов и локализация
* Плотная региональная генерация подписей
* Понимание референтных выражений
* OCR и распознавание текста
* Визуальные вопросы и ответы

## Ресурсы

* **HuggingFace:** [microsoft/Florence-2-large](https://huggingface.co/microsoft/Florence-2-large)
* **Статья:** [Статья о Florence-2](https://arxiv.org/abs/2311.06242)
* **GitHub:** [microsoft/Florence-2](https://github.com/microsoft/Florence-2)
* **Демо:** [HuggingFace Space](https://huggingface.co/spaces/microsoft/Florence-2)

## Рекомендованное оборудование

| Компонент | Минимум       | Рекомендуется | Оптимально    |
| --------- | ------------- | ------------- | ------------- |
| GPU       | RTX 3060 12GB | RTX 4080 16GB | RTX 4090 24GB |
| VRAM      | 8GB           | 12GB          | 16GB          |
| CPU       | 4 ядра        | 8 ядер        | 16 ядер       |
| ОЗУ       | 16GB          | 32GB          | 64GB          |
| Хранилище | 30GB SSD      | 50GB NVMe     | 100GB NVMe    |
| Интернет  | 100 Мбит/с    | 500 Мбит/с    | 1 Гбит/с      |

## Быстрое развертывание на CLORE.AI

**Docker-образ:**

```
pytorch/pytorch:2.5.1-cuda12.4-cudnn9-devel
```

**Порты:**

```
22/tcp
7860/http
```

**Команда:**

```bash
pip install transformers accelerate einops timm gradio && \
python -c "
import gradio as gr
from transformers import AutoProcessor, AutoModelForCausalLM
import torch
from PIL import Image

model = AutoModelForCausalLM.from_pretrained('microsoft/Florence-2-large', torch_dtype=torch.float16, trust_remote_code=True).to('cuda')
processor = AutoProcessor.from_pretrained('microsoft/Florence-2-large', trust_remote_code=True)

def process(image, task):
    inputs = processor(text=task, images=image, return_tensors='pt').to('cuda', torch.float16)
    generated_ids = model.generate(input_ids=inputs['input_ids'], pixel_values=inputs['pixel_values'], max_new_tokens=1024)
    result = processor.batch_decode(generated_ids, skip_special_tokens=False)[0]
    return processor.post_process_generation(result, task=task, image_size=image.size)

gr.Interface(fn=process, inputs=[gr.Image(type='pil'), gr.Dropdown(['<CAPTION>', '<DETAILED_CAPTION>', '<OD>'])], outputs='json').launch(server_name='0.0.0.0')
"
```

## Доступ к вашему сервису

После развертывания найдите ваш `http_pub` URL в **Моих заказах**:

1. Перейдите на **Моих заказах** страницу
2. Нажмите на ваш заказ
3. Найдите `http_pub` URL (например, `abc123.clorecloud.net`)

Используйте `https://YOUR_HTTP_PUB_URL` вместо `localhost` в примерах ниже.

## Установка

```bash
pip install transformers accelerate einops timm
pip install flash-attn --no-build-isolation  # Опционально, для более быстрой инференции
```

## Что вы можете создать

### Анализ контента

* Авто‑генерация описаний изображений
* Извлечение текста из изображений (OCR)
* Анализ визуального контента в масштабах

### Аннотация данных

* Автоматическая разметка наборов данных с подписями
* Генерация ограничивающих рамок для объектов
* Создание плотных аннотаций

### Доступность

* Генерация alt-текста для изображений
* Описание изображений для людей с нарушением зрения
* Создание аудиоописаний

### Поиск и обнаружение

* Индексация изображений по содержимому
* Построение систем визуального поиска
* Модерация контента

### Обработка документов

* Извлечение текста из документов
* Понимание диаграмм и графиков
* Обработка отсканированных материалов

## Базовое использование

### Генерация подписей к изображениям

```python
from transformers import AutoProcessor, AutoModelForCausalLM
from PIL import Image
import torch

model = AutoModelForCausalLM.from_pretrained(
    "microsoft/Florence-2-large",
    torch_dtype=torch.float16,
    trust_remote_code=True
).to("cuda")

processor = AutoProcessor.from_pretrained(
    "microsoft/Florence-2-large",
    trust_remote_code=True
)

image = Image.open("photo.jpg")

# Краткая подпись
task = "<CAPTION>"
inputs = processor(text=task, images=image, return_tensors="pt").to("cuda", torch.float16)
generated_ids = model.generate(
    input_ids=inputs["input_ids"],
    pixel_values=inputs["pixel_values"],
    max_new_tokens=1024
)
result = processor.batch_decode(generated_ids, skip_special_tokens=False)[0]
caption = processor.post_process_generation(result, task=task, image_size=image.size)
print(caption)

# Вывод: {'<CAPTION>': 'Собака играет в парке'}

# Подробная подпись
task = "<DETAILED_CAPTION>"
inputs = processor(text=task, images=image, return_tensors="pt").to("cuda", torch.float16)
generated_ids = model.generate(
    input_ids=inputs["input_ids"],
    pixel_values=inputs["pixel_values"],
    max_new_tokens=1024
)
result = processor.batch_decode(generated_ids, skip_special_tokens=False)[0]
detailed = processor.post_process_generation(result, task=task, image_size=image.size)
print(detailed)
```

### Обнаружение объектов

```python
task = "<OD>"  # Обнаружение объектов
inputs = processor(text=task, images=image, return_tensors="pt").to("cuda", torch.float16)
generated_ids = model.generate(
    input_ids=inputs["input_ids"],
    pixel_values=inputs["pixel_values"],
    max_new_tokens=1024
)
result = processor.batch_decode(generated_ids, skip_special_tokens=False)[0]
detections = processor.post_process_generation(result, task=task, image_size=image.size)

# Вывод: {'<OD>': {'bboxes': [[x1, y1, x2, y2], ...], 'labels': ['dog', 'ball', ...]}}
```

### OCR (распознавание текста)

```python
task = "<OCR>"
inputs = processor(text=task, images=image, return_tensors="pt").to("cuda", torch.float16)
generated_ids = model.generate(
    input_ids=inputs["input_ids"],
    pixel_values=inputs["pixel_values"],
    max_new_tokens=1024
)
result = processor.batch_decode(generated_ids, skip_special_tokens=False)[0]
text = processor.post_process_generation(result, task=task, image_size=image.size)
print(text)

# Вывод: {'<OCR>': 'Текст, найденный на изображении...'}
```

### Плотная региональная генерация подписей

```python
task = "<DENSE_REGION_CAPTION>"
inputs = processor(text=task, images=image, return_tensors="pt").to("cuda", torch.float16)
generated_ids = model.generate(
    input_ids=inputs["input_ids"],
    pixel_values=inputs["pixel_values"],
    max_new_tokens=1024
)
result = processor.batch_decode(generated_ids, skip_special_tokens=False)[0]
regions = processor.post_process_generation(result, task=task, image_size=image.size)

# Вывод: {'<DENSE_REGION_CAPTION>': {'bboxes': [...], 'labels': ['коричневая собака бегает', 'зелёная трава', ...]}}
```

### Понимание референтных выражений

Найдите объекты по текстовым описаниям:

```python
task = "<CAPTION_TO_PHRASE_GROUNDING>"
text_input = "the red car on the left"

inputs = processor(
    text=task + text_input,
    images=image,
    return_tensors="pt"
).to("cuda", torch.float16)

generated_ids = model.generate(
    input_ids=inputs["input_ids"],
    pixel_values=inputs["pixel_values"],
    max_new_tokens=1024
)
result = processor.batch_decode(generated_ids, skip_special_tokens=False)[0]
grounding = processor.post_process_generation(result, task=task, image_size=image.size)

# Возвращает ограничивающую рамку для "the red car on the left"
```

## Все доступные задачи

```python
TASKS = [
    "<CAPTION>",                    # Краткая подпись
    "<DETAILED_CAPTION>",           # Подробное описание
    "<MORE_DETAILED_CAPTION>",      # Очень подробное описание
    "<OD>",                          # Обнаружение объектов
    "<DENSE_REGION_CAPTION>",       # Описания регионов
    "<REGION_PROPOSAL>",            # Предложить регионы интереса
    "<CAPTION_TO_PHRASE_GROUNDING>", # Найти объекты по тексту
    "<REFERRING_EXPRESSION_SEGMENTATION>", # Сегментация по тексту
    "<REGION_TO_SEGMENTATION>",     # Сегментировать указанный регион
    "<OPEN_VOCABULARY_DETECTION>",  # Обнаружение с текстовыми метками
    "<REGION_TO_CATEGORY>",         # Классифицировать регион
    "<REGION_TO_DESCRIPTION>",      # Описать регион
    "<OCR>",                         # Извлечь текст
    "<OCR_WITH_REGION>",            # Извлечь текст с указанием местоположения
]
```

## Пакетная обработка

```python
import os
from transformers import AutoProcessor, AutoModelForCausalLM
from PIL import Image
import torch
import json

model = AutoModelForCausalLM.from_pretrained(
    "microsoft/Florence-2-large",
    torch_dtype=torch.float16,
    trust_remote_code=True
).to("cuda")
processor = AutoProcessor.from_pretrained("microsoft/Florence-2-large", trust_remote_code=True)

def process_image(image_path, task):
    image = Image.open(image_path)
    inputs = processor(text=task, images=image, return_tensors="pt").to("cuda", torch.float16)
    generated_ids = model.generate(
        input_ids=inputs["input_ids"],
        pixel_values=inputs["pixel_values"],
        max_new_tokens=1024
    )
    result = processor.batch_decode(generated_ids, skip_special_tokens=False)[0]
    return processor.post_process_generation(result, task=task, image_size=image.size)

# Обработать каталог
input_dir = "./images"
results = {}

for filename in os.listdir(input_dir):
    if not filename.endswith(('.jpg', '.png')):
        continue

    path = os.path.join(input_dir, filename)
    results[filename] = {
        "caption": process_image(path, "<CAPTION>"),
        "objects": process_image(path, "<OD>"),
        "text": process_image(path, "<OCR>")
    }
    print(f"Обработано: {filename}")

with open("results.json", "w") as f:
    json.dump(results, f, indent=2)
```

## Интерфейс Gradio

```python
import gradio as gr
from transformers import AutoProcessor, AutoModelForCausalLM
from PIL import Image, ImageDraw
import torch

model = AutoModelForCausalLM.from_pretrained(
    "microsoft/Florence-2-large",
    torch_dtype=torch.float16,
    trust_remote_code=True
).to("cuda")
processor = AutoProcessor.from_pretrained("microsoft/Florence-2-large", trust_remote_code=True)

def run_task(image, task):
    inputs = processor(text=task, images=image, return_tensors="pt").to("cuda", torch.float16)
    generated_ids = model.generate(
        input_ids=inputs["input_ids"],
        pixel_values=inputs["pixel_values"],
        max_new_tokens=1024
    )
    result = processor.batch_decode(generated_ids, skip_special_tokens=False)[0]
    parsed = processor.post_process_generation(result, task=task, image_size=image.size)

    # Нарисовать рамки, если задача — детекция
    output_image = image.copy()
    if task in ["<OD>", "<DENSE_REGION_CAPTION>"]:
        draw = ImageDraw.Draw(output_image)
        if "bboxes" in parsed.get(task, {}):
            for box, label in zip(parsed[task]["bboxes"], parsed[task]["labels"]):
                draw.rectangle(box, outline="red", width=2)
                draw.text((box[0], box[1]-15), label, fill="red")

    return output_image, str(parsed)

demo = gr.Interface(
    fn=run_task,
    inputs=[
        gr.Image(type="pil", label="Входное изображение"),
        gr.Dropdown(
            choices=["<CAPTION>", "<DETAILED_CAPTION>", "<OD>", "<DENSE_REGION_CAPTION>", "<OCR>"],
            value="<CAPTION>",
            label="Задача"
        )
    ],
    outputs=[
        gr.Image(label="Результат"),
        gr.Textbox(label="Вывод", lines=10)
    ],
    title="Florence-2 Vision AI",
    description="Многофункциональная визуальная модель. Запускается на GPU‑серверах CLORE.AI."
)

demo.launch(server_name="0.0.0.0", server_port=7860)
```

## Производительность

| Задача               | Разрешение | GPU      | Скорость |
| -------------------- | ---------- | -------- | -------- |
| Подпись              | 768x768    | RTX 3090 | 200ms    |
| Подпись              | 768x768    | RTX 4090 | 120ms    |
| Обнаружение объектов | 768x768    | RTX 4090 | 150ms    |
| OCR                  | 768x768    | RTX 4090 | 180ms    |
| Плотная подпись      | 768x768    | A100     | 100ms    |

## Варианты моделей

| Модель              | Параметры | VRAM | Скорость |
| ------------------- | --------- | ---- | -------- |
| Florence-2-base     | 232M      | 4 ГБ | Быстро   |
| Florence-2-large    | 771M      | 8GB  | Средне   |
| Florence-2-base-ft  | 232M      | 4 ГБ | Быстро   |
| Florence-2-large-ft | 771M      | 8GB  | Средне   |

## Распространённые проблемы и решения

### Недостаточно памяти

**Проблема:** Ошибка CUDA OOM

**Решения:**

```python

# Используйте базовую модель вместо большой
model = AutoModelForCausalLM.from_pretrained(
    "microsoft/Florence-2-base",
    torch_dtype=torch.float16,
    trust_remote_code=True
).to("cuda")

# Или включите выгрузку на CPU
model = AutoModelForCausalLM.from_pretrained(
    "microsoft/Florence-2-large",
    torch_dtype=torch.float16,
    trust_remote_code=True,
    device_map="auto"
)
```

### Медленная инференция

**Проблема:** Обработка занимает слишком много времени

**Решения:**

* Используйте Florence-2-base для более быстрой инференции
* Установите flash-attention для ускорения
* Объединяйте несколько изображений в пакет
* Используйте GPU A100 для продакшена

```bash
pip install flash-attn --no-build-isolation
```

### Плохие результаты OCR

**Проблема:** Распознавание текста неточно

**Решения:**

* Убедитесь, что изображение высокого разрешения (как минимум 768px)
* Используйте `<OCR_WITH_REGION>` для лучшей локализации
* Предобработка: усилите контраст, выровняйте изображение
* Обрезайте до областей с текстом перед OCR

### Детекция не находит объекты

**Проблема:** Объекты не обнаруживаются

**Решения:**

* Используйте `<DENSE_REGION_CAPTION>` для большего количества регионов
* Попробуйте `<OPEN_VOCABULARY_DETECTION>` с конкретными метками
* Комбинируйте с GroundingDINO для поиска конкретных объектов

## Устранение неполадок

### Задача не работает

* Проверьте точный синтаксис имени задачи
* Некоторым задачам требуется специфический формат ввода
* Убедитесь, что версия модели соответствует задаче

### Непредвиденный формат вывода

* Разные задачи возвращают разные форматы
* Парсите вывод в соответствии с типом задачи
* Проверьте документацию по выходным данным задач

### Проблемы с памятью CUDA

* Florence-2-large требует \~8GB видеопамяти
* Используйте Florence-2-base для меньшего потребления памяти
* Включите gradient checkpointing

### Медленная обработка

* Используйте пакетную инференцию, когда это возможно
* Включите режим FP16
* Рассмотрите оптимизацию с помощью TensorRT

## Оценка стоимости

Типичные ставки на маркетплейсе CLORE.AI (по состоянию на 2024):

| GPU       | Почасовая ставка | Дневная ставка | Сессия 4 часа |
| --------- | ---------------- | -------------- | ------------- |
| RTX 3060  | \~$0.03          | \~$0.70        | \~$0.12       |
| RTX 3090  | \~$0.06          | \~$1.50        | \~$0.25       |
| RTX 4090  | \~$0.10          | \~$2.30        | \~$0.40       |
| A100 40GB | \~$0.17          | \~$4.00        | \~$0.70       |
| A100 80GB | \~$0.25          | \~$6.00        | \~$1.00       |

*Цены варьируются в зависимости от провайдера и спроса. Проверьте* [*CLORE.AI Marketplace*](https://clore.ai/marketplace) *для текущих тарифов.*

**Экономьте деньги:**

* Используйте **Spot** рынок для гибких рабочих нагрузок (часто на 30–50% дешевле)
* Платите с помощью **CLORE** токенов
* Сравнивайте цены у разных провайдеров

## Дальнейшие шаги

* [LLaVA](https://docs.clore.ai/guides/guides_v2-ru/modeli-zreniya/llava-vision-language) - Визуальный чат и вопросы-ответы
* [GroundingDINO](https://docs.clore.ai/guides/guides_v2-ru/modeli-zreniya/groundingdino) - Нулевой-shot детекция
* [SAM2](https://docs.clore.ai/guides/guides_v2-ru/modeli-zreniya/sam2-video) - Сегментация обнаруженных объектов