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
AI-Powered Alt Text Generation with mostlylucidM SK1llmlltText
Tuesday, 25 November 2025
Хочете отримати гарний, дескриптивний alt-текст для зображення на ваших сайтах або текст із jsut extract з них? mostlylucid.llmalttext використовує модель Microsoft's ФлоренціяM SK1 візуального мови для генерації високої якості alt-тексту automatічно - запускається повністю локально на вашому машині
Примітка: Я повинен оновити цей документ зараз пакет нугета це позаду. Якщо ви поглянете тут ви' зробимо чудову демонстраційну веб-страницу, яку можна завантажити і використати
Введение
Альт-текст має значення. Читачі екранів залежать від нього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_textllmalttext.extract_textllmalttext.analyze_imagellmalttext.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
- Переглянути результат - штучний інтелект не є
- Залиште це коротко. МSK0 90-100 max. слова
- Бути описливим - включає в себе суб 'єкти, діїM SK2 контекст
- Уникнення надлишків - donM SK1 не починайте з "Зображення МSK3
- Розглянемо ціль - alt текст мав би служити ролику зображення ' на сторінці
- Використовуйте пустий alt для декоративних речей Набір -
alt=""для чисто декоративних образів - Включити видимий текст - якщо зображення містить текст
Завершення
Mostlylucid.LlmAltText надає - потужну доступність до ваших .NET-пристосувань без жодних витрат чи занепокоєнь з точки зору приватності зовнішніх API МSK2 TagHelper робить це особливо легким МSK3 просто дозволяє йому та вашому <img> Tags gain automatic alt text.
Пакет - Без ліцензії . ( публічний домен. ), тож робіть з ним все, що хочете.
Ресурс
- NuGet: Найяскравіший.LlmAltText
- Источник: github.com /scottgal/mostlylucidM SK3nugetpackages
- Публикації: Проблеми в GitHub
- Флоренція-2: Microsoft's Vision Language Model