Index images without OCR text and route vision analysis through its AI connection

[Paul Lizer (paullizer)]

Refs #1583

Summary

Text-free images, such as an overexposed photo of an empty lab floor, ended with Processing complete - no text found in image: no title, 0 chunks in AI Search, and nothing chat could use, even though the vision model had described them. This PR indexes the vision description when OCR finds no text, falls back to Content Understanding's image analyzer for standalone images, and calls the vision model on the AI connection that actually hosts it.

It also raises the default Azure OpenAI image generation API version to 2025-04-01-preview (separate section below). One version bump, 0.261.047, covers both.

Root cause

• Only OCR text could create an image chunk. CU prebuilt-documentSearch returned no pages, so extraction fell back to DI prebuilt-layout. Layout read floor tape as the page number J (<!-- PageNumber="J" -->) on one photo and returned nothing for the other. The bogus comment became the first photo's only chunk; the second got none, so final metadata extraction was skipped too.
• The vector ignored the description. save_chunks appended the vision block after embedding the OCR text (embedding - 7 tokens).
• CU's image description was discarded. prebuilt-imageSearch returns ![image](pages/1) as markdown and the description in fields.Summary.valueString, which analyze_image_with_content_understanding ignored.
• The vision model ignored its AI connection. analyze_image_with_vision_model always used the legacy azure_openai_gpt_*/APIM client, so gpt-5.6-luna (deployed only on another connection) returned 404, while the admin test resolved the real connection and passed.

Changes

Index image descriptions when OCR finds no text (functions_documents.py)

• _format_vision_analysis_block() replaces the duplicated inline formatting. Valid analyses keep the exact === AI Vision Analysis === format; missing, non-dict, error, or empty analyses return ''.
• save_chunks() builds the stored text (OCR + vision block, no leading blank lines when OCR is empty) before embedding and embeds that same text, keeping the last-resort clamp guard. It never writes an empty chunk. save_chunks_batch() uses the same helpers.
• process_di_document() records whether this run produced a usable vision analysis, keeps only image OCR pages with real text, and otherwise saves one description-only page-1 chunk (flagged vision_description_only). Final metadata extraction then runs. Images with real OCR text are unchanged; vision still runs only with Enhanced Citations on.

Content Understanding image analyzer fallback (functions_content_understanding.py, functions_content.py, route_frontend_chats.py)

• analyze_image_with_content_understanding() emits Summary as plain text and other string fields as Name: value, ignores placeholder-only markdown, and keeps figure summaries. This also fixes images embedded in DOCX/PPTX files analyzed with CU, which were indexed with just the ![image](pages/1) placeholder.
• extract_content_with_extraction_engine(..., is_image=False): when the document analyzer returns nothing for an image, the image analyzer's description becomes page 1 with the reason Content Understanding found no text, so its image analyzer description was indexed. If it fails or returns nothing, extraction falls back to DI Layout exactly as before (with a warning). PDFs and other files are unchanged. Workspace uploads thread is_image from process_di_document; direct chat uploads pass is_image=is_image_file.

Route the vision model through its AI connection (functions_model_endpoint_types.py, functions_documents.py, route_backend_settings.py)

• New pure find_enabled_model_endpoint_for_model_name(endpoints, model_name) → (endpoint, model) or (None, None): enabled endpoints/models only; deployment name or resolved request model first, then model name, then id; first match in endpoint order.
• _build_model_endpoint_client_for_model() now holds the client construction moved out of _resolve_metadata_extraction_client (Key Vault resolution, request model, API version/protocol checks, provider allowlist). Metadata extraction keeps the same behavior, order, and error messages.
• analyze_image_with_vision_model() uses the matched connection and sends model=<resolved request model> via resolve_vision_model_endpoint(); otherwise the legacy APIM/direct client is unchanged. It logs the connection by name/id only and still returns None on errors. Chat image uploads benefit automatically.
• _test_multimodal_vision_connection() now resolves the name the same way, so Test Vision Analysis uses the ingestion connection, including when APIM is checked with multi-endpoint models enabled (previously it tested APIM while ingestion would not).

Image generation API version default

• azure_openai_image_gen_api_version now defaults to AZURE_OPENAI_IMAGE_GEN_API_VERSION_DEFAULT = '2025-04-01-preview', the newest dated Azure OpenAI version and the one documented for gpt-image-1, 1.5, and 2. 2024-12-01-preview predates gpt-image support.
• normalize_image_generation_api_version_settings(), run from normalize_loaded_settings(), upgrades a stored value that is exactly the previous default (AZURE_OPENAI_IMAGE_GEN_API_VERSION_PREVIOUS_DEFAULT) or blank. Any other value is kept. azure_apim_image_gen_api_version is never changed because the gateway defines its version.
• Updated docs/admin/ai-models.md, artifacts/cosmos_examples/cosmos-settings-example.json, and the database seeder admin_settings.json (image generation entries only).

Tests

• functional_tests/test_image_description_indexing_without_ocr_text.py (8 tests): pure lookup tests in-process; real modules in fresh normal and -O processes with external I/O blocked, reusing the issue payloads (CU prebuilt-imageSearch result, empty/PageNumber="J" DI output). Covers vision block formatting, save/embed parity, description-only chunks, header-only OCR kept, CU Summary parsing and fallback, vision connection lookup and legacy fallback, unchanged metadata-extraction client behavior and messages, the admin test agreement, and the chat call site.
• functional_tests/test_image_generation_api_version_default.py (17 tests): default, migration cases (old default, blank, custom 2025-03-01-preview untouched, APIM untouched), wiring, docs/artifacts, and a real get_settings() load that persists the migration.
• Re-ran related suites (Content Understanding, Office embedded images, figure chunks, vision multi-endpoint, DI extraction mode and reprocess, privacy logging audit, model endpoint providers, settings store/migration suites, docs coverage and quality, route policy suites), plus the BAC, XSS, and swagger guardrails: all pass. Pre-existing failures are unchanged: test_markdown_chunk_size_enforcement.py (4/8), test_vision_model_parameter_fix.py, test_document_auto_metadata_extraction_consistency.py (3/4), test_multiselect_metadata_extraction.py (4/5), test_image_generation_model_compatibility.py (2/4).

Notes

• Existing images are not re-indexed automatically; re-upload affected images (Change Extraction re-indexes but does not re-run metadata extraction).
• Only PageNumber/PageBreak comments count as non-text; PageHeader/PageFooter comments carry recognized text and still count, so header- or footer-only images are not dropped.
• The vision setting stores only a name, so a name present on several enabled connections resolves by the precedence above.

Docs: docs/explanation/fixes/IMAGE_DESCRIPTION_INDEXING_WITHOUT_OCR_TEXT_FIX.md, docs/explanation/fixes/IMAGE_GENERATION_API_VERSION_DEFAULT_FIX.md, release notes under 0.261.047, and updates to docs/admin/knowledge.md, docs/admin/workspaces.md, and the Content Understanding feature doc.