Back to "AI-Powered Alt Text Generation with mostlylucidM SK1llmlltText"

This is a viewer only at the moment see the article on how this works.

To update the preview hit Ctrl-Alt-R (or ⌘-Alt-R on Mac) or Enter to refresh. The Save icon lets you save the markdown file to disk

This is a preview from the server running through my markdig pipeline

Accessibility AI ASP.NET Florence-2 Image Processing NuGet

AI-Powered Alt Text Generation with mostlylucidM SK1llmlltText

Tuesday, 25 November 2025

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

Примітка: Я повинен оновити цей документ зараз пакет нугета це позаду. Якщо ви поглянете тут ви' зробимо чудову демонстраційну веб-страницу, яку можна завантажити і використати

NuGet Лицензія: Нелицензія

Введение

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

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

вихідний код: github.com /scottgal/mostlylucidM SK3nugetpackages

Проблема

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

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

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

Як це працює

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

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
  • класифікація контенту - знає, чи це фотографія

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

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

dotnet add package Mostlylucid.LlmAltText

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

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

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

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

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 або ж байтові массиви .

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

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

Від URL

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

Від потоку

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

Від Byte Array

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

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

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

// 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

// 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}");

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

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

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}");

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

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.

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

// 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:

@addTagHelper *, Mostlylucid.LlmAltText

Як це працює

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

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

<!-- 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 перейде з:

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

Caching бази даних

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

SQLite (Development)

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

PostgreSQL (Production)

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

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

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

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

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

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

// 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

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

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

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

  • llmalttext.generate_alt_text
  • llmalttext.extract_text
  • llmalttext.analyze_image
  • llmalttext.classify_content_type

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

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

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

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

_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.

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

Ресурс

logo

© 2026 Scott Galloway — Unlicense — All content and source code on this site is free to use, copy, modify, and sell.