# AI-Powered Alt Text Generation with mostlylucidM SK1llmlltText

Хочете отримати гарний, дескриптивний alt-текст для зображення на ваших сайтах або текст із jsut extract з них? `mostlylucid.llmalttext` використовує модель Microsoft's ФлоренціяM SK1 візуального мови для генерації високої якості alt-тексту automatічно - запускається повністю локально на вашому машині

> Примітка: Я повинен оновити цей документ зараз [пакет нугета ](https://www.nuget.org/packages/Mostlylucid.LlmAltText)це позаду. Якщо ви поглянете [тут](https://github.com/scottgal/mostlylucid.nugetpackages/tree/main/Mostlylucid.AltText.Demo) ви' зробимо чудову демонстраційну веб-страницу, яку можна завантажити і використати

<datetime class="hidden">2025-11-25T14:00</datetime>

<!-- category -- ASP.NET, Accessibility, AI, NuGet, Florence-2, Image Processing -->
[![NuGet](https://img.shields.io/nuget/v/mostlylucid.llmaltText.svg)](https://www.nuget.org/packages/mostlylucid.llmalttext) [![Лицензія: Нелицензія](https://img.shields.io/badge/license-Unlicense-blue.svg)](http://unlicense.org/)

# Введение

Альт-текст має значення. Читачі екранів залежать від ньогоM SK1 Рейтинги SEO враховують його в рейтингі , і це МSK3 це просто правильна річ для доступності M SK4 Але писати хороший alt-текст для сотень зображень ? Це М SK6 там, де більшість з нас недосягають

Цей пакет вирішує цю проблему, використовуючи модель Microsoft's Florence-2 візуального мовного моделі - яка працює повністю локально на вашій машині

**вихідний код:** [github.com /scottgal/mostlylucidM SK3nugetpackages](https://github.com/scottgal/mostlylucid.nugetpackages/tree/main/Mostlylucid.LlmAltText)

[TOC]

# Проблема

Кожного `<img>` знак має мати змістовний alt текст. Але в практиціM SK1

- **Ручне письмо - нудно.** - Сотні фотографій - це години роботи
- **ШІ-API коштують грошей** - OpenAI Vision , ClaudeM SK2 і т.д.
- **Занепокоєння щодо приватності** - ви можете не хочете надсилати зображення на зовнішні API
- **Недосконалість якості** - різні люди пишуть alt-текст по-різному

Що, якби ви могли генерувати високоякісний alt-текст automatічно на вашому самому апараті?

# Як це працює

Pakiet використовує модель Майкрософту' ФлоренціїM SK1 за допомогою ONNX runtime. ТутMSC3 це обробка каналуMST4

```mermaid
flowchart TB
    subgraph Input[Image Sources]
        A[File Path]
        B[URL]
        C[Stream]
        D[Byte Array]
    end

    subgraph Processing[Florence-2 Pipeline]
        E[Image Preprocessing]
        F[Vision Encoder]
        G[Language Decoder]
    end

    subgraph Output[Results]
        H[Alt Text]
        I[OCR Text]
        J[Content Type]
    end

    A --> E
    B --> E
    C --> E
    D --> E
    E --> F
    F --> G
    G --> H
    G --> I
    G --> J

    style A stroke:#10b981,stroke-width:2px
    style B stroke:#10b981,stroke-width:2px
    style C stroke:#10b981,stroke-width:2px
    style D stroke:#10b981,stroke-width:2px
    style F stroke:#6366f1,stroke-width:2px
    style G stroke:#6366f1,stroke-width:2px
    style H stroke:#ec4899,stroke-width:2px
    style I stroke:#ec4899,stroke-width:2px
    style J stroke:#ec4899,stroke-width:2px
```

**Головні характеристики:**

- **Локальне виконання** - без API дзвінків , без витрат M SK2 без проблем з конфіденційністю
- **Модель ~800MB** - завантажується один разM SK1 зберігається в пам 'яті назавжди
- **Багато типів задач** - короткі субтитры , деталізовані описи МSK2 ОCR
- **класифікація контенту** - знає, чи це фотографія

# Швидкий старт

## Установлення

```bash
dotnet add package Mostlylucid.LlmAltText
```

## Услуги реєстрування

```csharp
// Program.cs
builder.Services.AddAltTextGeneration();
```

МSK1 - це перший запуск, який завантажує модель Флоренції. МSK2 - модель Флорентії.

## Створити Alt-текст

```csharp
public class ImageController : ControllerBase
{
    private readonly IImageAnalysisService _imageAnalysis;

    public ImageController(IImageAnalysisService imageAnalysis)
    {
        _imageAnalysis = imageAnalysis;
    }

    [HttpPost("analyze")]
    public async Task<IActionResult> Analyze(IFormFile image)
    {
        using var stream = image.OpenReadStream();
        var altText = await _imageAnalysis.GenerateAltTextAsync(stream);

        return Ok(new { altText });
    }
}
```

# Багато джерел вхідних даних

Ця служба сприймає зображення з будь-якого місця: - файли , URLs M SK2 потоки МSK3 або ж байтові массиви .

## Від Шляху Файлів

```csharp
var altText = await _imageAnalysis.GenerateAltTextFromFileAsync("/images/photo.jpg");
```

## Від URL

```csharp
var altText = await _imageAnalysis.GenerateAltTextFromUrlAsync(
    "https://example.com/image.png");
```

## Від потоку

```csharp
using var stream = file.OpenReadStream();
var altText = await _imageAnalysis.GenerateAltTextAsync(stream);
```

## Від Byte Array

```csharp
var bytes = await httpClient.GetByteArrayAsync(imageUrl);
var altText = await _imageAnalysis.GenerateAltTextAsync(bytes);
```

# Типи завдань: Уровни деталізації управління

Флоренція-2 підходить для трьох режимів субтитровM SK1 Вибирати в залежності від ваших потреб

```csharp
// Brief - "A dog sitting on grass"
var brief = await _imageAnalysis.GenerateAltTextAsync(stream, "CAPTION");

// Detailed - "A golden retriever sitting on green grass in a park"
stream.Position = 0;
var detailed = await _imageAnalysis.GenerateAltTextAsync(stream, "DETAILED_CAPTION");

// Most detailed (default) - Full accessibility description
stream.Position = 0;
var full = await _imageAnalysis.GenerateAltTextAsync(stream, "MORE_DETAILED_CAPTION");
// "A happy golden retriever with light fur sitting on lush green grass
//  in a sunny park, with trees visible in the background."
```

**Коли використовувати кожен**

| Тип завдання | Найкраще для МSK2
|-----------|----------|
| `CAPTION` | СуреткиM SK1 декоративні зображення, швидкі вказівники
| `DETAILED_CAPTION` | Спільні медіа , базова доступність МSK2
| `MORE_DETAILED_CAPTION` | Полна доступністьM SK1 екранні чтечі ( рекомендовані МSK3 МSK4

# Витягування тексту OCR

Флоренція-2 також може витягнути текст з зображеннях - корисне для скриншотів МSK2 документи МСК3 та діаграми М СК4

```csharp
// Extract text only
var extractedText = await _imageAnalysis.ExtractTextAsync(stream);

// Get both alt text and extracted text
var (altText, ocrText) = await _imageAnalysis.AnalyzeImageAsync(stream);

Console.WriteLine($"Alt: {altText}");
Console.WriteLine($"OCR: {ocrText}");
```

# Класифікація типу контенту

Не всі зображення однакові

```csharp
var result = await _imageAnalysis.AnalyzeWithClassificationAsync(stream);

Console.WriteLine($"Type: {result.ContentType}");        // e.g., "Photograph"
Console.WriteLine($"Confidence: {result.ContentTypeConfidence:P0}"); // e.g., "87%"
Console.WriteLine($"Has Text: {result.HasSignificantText}");
```

## Обробка різних типів контенту

```csharp
var result = await _imageAnalysis.AnalyzeWithClassificationAsync(stream);

switch (result.ContentType)
{
    case ImageContentType.Document:
        // Documents - prioritize extracted text
        return result.ExtractedText;

    case ImageContentType.Screenshot:
        // Screenshots - combine description with UI text
        return result.HasSignificantText
            ? $"{result.AltText}. Text visible: {result.ExtractedText}"
            : result.AltText;

    case ImageContentType.Chart:
        // Charts - describe the visualization plus data
        return $"{result.AltText}. Data: {result.ExtractedText}";

    case ImageContentType.Photograph:
    default:
        // Photos - just the description
        return result.AltText;
}
```

## Референція типу контенту

| Тип МSK1 Описание МSK2 Приклад |
|------|-------------|---------|
| `Photograph` | РеальнийM SK1Фотографії світу
| `Document` | ТекстM SK1важкий зміст МSK2 PDF-файлиМ SK3 бланки МSK4 статті |
| `Screenshot` | Програмне забезпечення
| `Chart` | візуалізація даних МSK1 Графи МSK2 графи з пирогами , таблиці
| `Illustration` | Створений контент МSK1 МистецтвоM SK2 мультфільми, іконки |
| `Diagram` | Технический малюнок
| `Unknown` | Не класифіковані | Корпуси з краями МSK2

# Автоматичний Alt Text TagHelper

Тут's, де стає цікаво. Помічник теги автоматично генерує alt текст для будь-якого `<img>` tag missing one - at render time.

## Налагодження

```csharp
// Program.cs
builder.Services.AddAltTextGeneration(options =>
{
    options.EnableTagHelper = true;
    options.EnableDatabase = true;  // Cache results
    options.DbProvider = AltTextDbProvider.Sqlite;
    options.SqliteDbPath = "./alttext.db";
});

var app = builder.Build();
await app.Services.MigrateAltTextDatabaseAsync();
```

Зарегиструйте в себе TagHelper `_ViewImports.cshtml`:

```cshtml
@addTagHelper *, Mostlylucid.LlmAltText
```

## Як це працює

```mermaid
flowchart LR
    subgraph Razor[Razor View Rendering]
        A[img tag found]
        B{Has alt attribute?}
        C[Skip - use existing]
        D{In cache?}
        E[Return cached]
        F[Fetch image]
        G[Generate alt text]
        H[Cache result]
        I[Render with alt]
    end

    A --> B
    B -->|Yes| C
    B -->|No| D
    D -->|Yes| E
    D -->|No| F
    F --> G
    G --> H
    H --> I
    E --> I

    style A stroke:#10b981,stroke-width:2px
    style B stroke:#6366f1,stroke-width:2px
    style G stroke:#ec4899,stroke-width:2px
    style I stroke:#8b5cf6,stroke-width:2px
```

## Що обробляється

```html
<!-- NO ALT - Will be processed -->
<img src="https://example.com/photo.jpg" />

<!-- HAS ALT - Skipped (respects your text) -->
<img src="https://example.com/photo.jpg" alt="My custom description" />

<!-- EMPTY ALT - Skipped (decorative image per a11y standards) -->
<img src="https://example.com/decorative.jpg" alt="" />

<!-- EXPLICIT SKIP - Skipped -->
<img src="https://example.com/photo.jpg" data-skip-alt="true" />

<!-- DATA URI - Skipped (can't fetch) -->
<img src="data:image/png;base64,..." />

<!-- RELATIVE PATH - Skipped (needs absolute URL) -->
<img src="/images/photo.jpg" />
```

## Ограничення доменів

Для безпеки, ви можете обмежити, які домени TagHelper перейде з:

```csharp
options.AllowedImageDomains = new List<string>
{
    "mycdn.example.com",
    "images.mysite.org",
    "cdn.githubusercontent.com"
};
```

# Caching бази даних

Безキャッシュу, кожен render сторінки буде відновлювати alt-текстM SK1 Це ' заповільне і марнотратне. Cache бази даних зберігає результати, зашифровані на URL зображення

## SQLite (Development)

```csharp
builder.Services.AddAltTextGeneration(options =>
{
    options.EnableDatabase = true;
    options.DbProvider = AltTextDbProvider.Sqlite;
    options.SqliteDbPath = "./alttext.db";
    options.CacheDurationMinutes = 60;
});
```

## PostgreSQL (Production)

```csharp
builder.Services.AddAltTextGeneration(options =>
{
    options.EnableDatabase = true;
    options.DbProvider = AltTextDbProvider.PostgreSql;
    options.ConnectionString = Configuration.GetConnectionString("AltTextDb");
});
```

# Конфігурація

```csharp
builder.Services.AddAltTextGeneration(options =>
{
    // Model location (~800MB downloaded here)
    options.ModelPath = "./models";

    // Default task type for alt text generation
    options.DefaultTaskType = "MORE_DETAILED_CAPTION";

    // Maximum word count for alt text
    options.MaxWords = 90;

    // Enable detailed logging
    options.EnableDiagnosticLogging = true;

    // TagHelper settings
    options.EnableTagHelper = true;
    options.EnableDatabase = true;
    options.AutoMigrateDatabase = true;

    // Database provider
    options.DbProvider = AltTextDbProvider.Sqlite;
    options.SqliteDbPath = "alttext.db";
    // or
    options.DbProvider = AltTextDbProvider.PostgreSql;
    options.ConnectionString = "Host=localhost;Database=alttext;...";

    // Security
    options.AllowedImageDomains = new List<string> { "cdn.example.com" };
    options.SkipSrcPrefixes = new List<string> { "data:", "blob:" };

    // Caching
    options.CacheDurationMinutes = 60;
});
```

# Реальний-World Example: Batch Processing

Ось як я користуюся ним для обробки зображень при введення блогових постів.

```csharp
public class ImageProcessor
{
    private readonly IImageAnalysisService _imageAnalysis;
    private readonly ILogger<ImageProcessor> _logger;

    public ImageProcessor(
        IImageAnalysisService imageAnalysis,
        ILogger<ImageProcessor> logger)
    {
        _imageAnalysis = imageAnalysis;
        _logger = logger;
    }

    public async Task ProcessMarkdownImagesAsync(string markdownPath)
    {
        var imageDir = Path.Combine(Path.GetDirectoryName(markdownPath)!, "images");
        if (!Directory.Exists(imageDir)) return;

        var images = Directory.GetFiles(imageDir, "*.*")
            .Where(f => IsImageFile(f));

        foreach (var imagePath in images)
        {
            try
            {
                var result = await _imageAnalysis
                    .AnalyzeWithClassificationFromFileAsync(imagePath);

                _logger.LogInformation(
                    "Processed {File}: {Type} ({Confidence:P0})",
                    Path.GetFileName(imagePath),
                    result.ContentType,
                    result.ContentTypeConfidence);

                // Store alt text for later use
                await SaveAltTextAsync(imagePath, result.AltText);
            }
            catch (Exception ex)
            {
                _logger.LogWarning(ex, "Failed to process {File}", imagePath);
            }
        }
    }

    private static bool IsImageFile(string path)
    {
        var ext = Path.GetExtension(path).ToLowerInvariant();
        return ext is ".jpg" or ".jpeg" or ".png" or ".gif" or ".webp" or ".bmp";
    }
}
```

# Рівень ефективності

## Що очікувати

| Метричне МSK1 Типове значення МSK2
|--------|--------------|
| Перший запуск | Повільніший МSK2 Загрузка моделі на МБ
| Завантаження моделі МSK1 МSK2 секунди |
| За МSK1обробка зображення мSK2 МSK3м |
| Використовування пам 'яті
| Дісковий простір | МSK2 МБ для моделей МSK3

## Совети для виробництва

```csharp
// 1. Register as Singleton (model load is expensive)
builder.Services.AddAltTextGeneration(); // Already singleton internally

// 2. Check readiness before processing
if (!_imageAnalysis.IsReady)
{
    return StatusCode(503, "AI model still initializing");
}

// 3. Use cancellation tokens for timeouts
var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
var altText = await _imageAnalysis.GenerateAltTextFromUrlAsync(url, cts.Token);

// 4. Process in batches, not parallel (memory constraints)
foreach (var image in images)
{
    await ProcessImageAsync(image); // Sequential is safer
}
```

# Інтеграція OpenTelemetry

У комплекті вбудована система відстеження-

```csharp
builder.Services.AddOpenTelemetry()
    .WithTracing(tracing =>
    {
        tracing.AddSource("Mostlylucid.LlmAltText");
    });
```

**Прослідкована діяльність:**

- `llmalttext.generate_alt_text`
- `llmalttext.extract_text`
- `llmalttext.analyze_image`
- `llmalttext.classify_content_type`

# Проверки здоров 'я

Додайте медичну перевірку, щоб контролювати статус моделі:

```csharp
public class AltTextHealthCheck : IHealthCheck
{
    private readonly IImageAnalysisService _service;

    public AltTextHealthCheck(IImageAnalysisService service)
        => _service = service;

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        return Task.FromResult(_service.IsReady
            ? HealthCheckResult.Healthy("Florence-2 model ready")
            : HealthCheckResult.Unhealthy("Model not initialized"));
    }
}

// Registration
builder.Services.AddHealthChecks()
    .AddCheck<AltTextHealthCheck>("alttext");
```

# Подолання проблем

## Не вдалось завантажити модель

```
Error: Failed to download model files
```

**Рішення:**

- Проверити підключення до Інтернету
- Перевірити брандмауэр, який дозволяє завантажувати Hugging Face
- Упевниться, що доступний дисковий простір ~800MB
- Проверка прав на написання `ModelPath`

## Сервис не готовий

```csharp
_imageAnalysis.IsReady // Returns false
```

**Рішення:**

- Почекайте на інициалізацію моделі (1-3 секундM SK1
- Проверяйте журнали щодо помилок при запускі
- Перевірити достатню пам 'ять (2GB+)

## Погана якість Alt Text

**Рішення:**

- Використовувати `MORE_DETAILED_CAPTION` (по замовчуваннюM SK1
- Упевниться, що зображення входу прозорі
- Подивіться, чи зображення не надто маленьке або тьмяне

## Не працює

**Рішення:**

- Перевірити `EnableTagHelper = true`
- Проверка `@addTagHelper` всередині `_ViewImports.cshtml`
- Використовуйте абсолютні URL ( відносні шляхи пропущені
- Проверка `AllowedImageDomains` конфігурація

# Найкращі практики з доступності

Згенерований альт-текст є початковою точкою. Для найкращих результатівM SK1

1. **Переглянути результат** - штучний інтелект не є
2. **Залиште це коротко.** МSK0 90-100 max. слова
3. **Бути описливим** - включає в себе суб 'єкти, діїM SK2 контекст
4. **Уникнення надлишків** - donM SK1 не починайте з "Зображення МSK3
5. **Розглянемо ціль** - alt текст мав би служити ролику зображення ' на сторінці
6. **Використовуйте пустий alt для декоративних речей** Набір - `alt=""` для чисто декоративних образів
7. **Включити видимий текст** - якщо зображення містить текст

# Завершення

`Mostlylucid.LlmAltText` надає - потужну доступність до ваших .NET-пристосувань без жодних витрат чи занепокоєнь з точки зору приватності зовнішніх API МSK2 TagHelper робить це особливо легким МSK3 просто дозволяє йому та вашому `<img>` Tags gain automatic alt text.

Пакет - Без ліцензії . ( публічний домен. ), тож робіть з ним все, що хочете.

## Ресурс

- **NuGet:** [Найяскравіший.LlmAltText](https://www.nuget.org/packages/Mostlylucid.LlmAltText)
- **Источник:** [github.com /scottgal/mostlylucidM SK3nugetpackages](https://github.com/scottgal/mostlylucid.nugetpackages/tree/main/Mostlylucid.LlmAltText)
- **Публикації:** [Проблеми в GitHub](https://github.com/scottgal/mostlylucidweb/issues)
- **Флоренція-2:** [Microsoft's Vision Language Model](https://huggingface.co/microsoft/Florence-2-base)