Extract Property Features

This guide walks through analyzing property photos using computer vision to generate descriptions, identify room types, and extract searchable features.

---

Before You Start

1. Ensure Ollama server is running and accessible
2. Verify the vision model is installed (ollama pull qwen2-vl)
3. Check system status on the Vision Extraction page
4. Confirm property_images table is populated — extraction needs one row per listing photo

Note

Extraction reads from the property_images table (one row per photo URL). New listings have rows created automatically when the MLS sync runs. For a fresh database or after a bulk import, run the backfill SQL once: it expands each listing’s properties.photos JSON array into individual rows. See the backfill snippet below.

---

What Users See After Extraction

Each listing’s Features tab has a “Detected in photos” section that surfaces vision tags grouped by type (Amenity, Appliance, Material, Room Type). Tags detected in multiple photos show a ×N multiplier — a confidence cue without any thresholding logic in the UI.

The frontend queries GET /api/listings/{listing_id}/feature-tags on tab mount; empty responses render nothing, so the tab degrades cleanly to the structured-data view until extraction has been run for the listing.

---

Prerequisite: Populating property_images

If property_images is empty (check via the Vision Extraction page’s “Unindexed” count), expand the listing photo arrays into per-image rows:

INSERT INTO property_images (listing_id, image_url, image_index, created_at)
SELECT
  p.listing_id,
  url_data.value::text,
  (url_data.ordinality - 1)::int,
  NOW()
FROM properties p
CROSS JOIN LATERAL jsonb_array_elements_text(p.photos::jsonb) WITH ORDINALITY AS url_data(value, ordinality)
WHERE p.standard_status = 'Active'
  AND p.photos IS NOT NULL
  AND jsonb_typeof(p.photos::jsonb) = 'array'
ON CONFLICT (listing_id, image_url) DO NOTHING;

The ON CONFLICT clause makes this safe to re-run.

---

Starting an Extraction Job

Navigate to Admin Dashboard → Vision and follow these steps:

1. Review the Unindexed Alert to see how many properties need processing
2. Click Start Extraction
3. Configure job options:
   • Limit — Process only a specific number of properties (leave empty for all)
   • Skip visual embeddings — Faster processing using description-based search only
4. Click Start Job

Note

Visual embeddings enable image similarity search but require more processing time. Description embeddings are sufficient for text-based semantic search.

---

Monitoring Job Progress

While a job is running, you’ll see a progress card displaying:

• Status badge — Current job state (pending, running, completed, failed)
• Progress bar — Visual completion indicator
• Image count — Processed vs. total images
• Start time — When the job began
• Cancel button — Stop the job if needed

The page updates automatically every 5 seconds.

Caution

Cancelling a job stops processing immediately. Already-processed images retain their descriptions and embeddings.

---

Testing with Small Batches

For initial setup or troubleshooting:

1. Start with a small limit (10-20 properties)
2. Monitor the job to completion
3. Review extraction history for any failures
4. Verify descriptions appear in property images
5. Gradually increase batch size

Tip

Start small to catch configuration issues before committing to large processing jobs.

---

Ongoing Maintenance

Regular Extraction Schedule

1. Schedule extraction jobs after MLS data syncs
2. Monitor coverage percentage on the dashboard
3. Aim for 100% coverage to ensure all photos are searchable
4. Run during off-peak hours to avoid impacting user searches

Reviewing Job History

Check the Extraction History table regularly:

• Identify recurring failures that need attention
• Track processing trends over time
• Monitor average duration per job
• Review which users triggered jobs

---

Troubleshooting

Job Fails Immediately

Symptoms: Job shows “failed” status within seconds

Solutions:

• Check Ollama server connectivity at the configured URL
• Verify the vision model is installed (ollama list)
• Review server logs for error details
• Test Ollama API manually: curl http://ollama-server:11434/api/version

Slow Processing

Symptoms: Job takes hours for small batches

Solutions:

• Reduce VISION_CONCURRENCY if server is overloaded
• Process in smaller batches (limit to 50-100 properties)
• Consider GPU acceleration for Ollama
• Check Ollama server resource usage (CPU, RAM, GPU)

Low Coverage Despite Completed Jobs

Symptoms: Coverage percentage stays low even after successful jobs

Solutions:

• Check failed image count in job history
• Some images may be corrupted or have inaccessible URLs
• Re-run extraction for specific properties with failures
• Review server logs for HTTP errors when fetching images

Features Not Appearing in Search

Symptoms: Extracted features don’t show up in semantic search

Solutions:

• Wait for embedding generation to complete fully
• Verify the search index has been updated
• Check that semantic search is enabled for the brokerage
• Test with explicit feature queries like “granite countertops”

---

Performance Tips

Skip Visual Embeddings

Use description-only mode for faster initial indexing

Use Limits

Process in manageable batches (100-500 properties)

Off-Peak Processing

Run large jobs during low-traffic hours

Monitor Resources

Watch Ollama server CPU/GPU usage during jobs

---

Related Documentation

• Vision Extraction Reference — Status indicators and configuration
• Vision Concepts — How computer vision works