---
title: EarthEmbeddingExplorer-Dense-Qwen3-VL-Embedding
canonical_url: "https://www.modelscope.cn/studios/Major-TOM/EarthEmbeddingExplorer-Dense-Qwen3-VL-Embedding"
md_url: "https://www.modelscope.cn/studios/Major-TOM/EarthEmbeddingExplorer-Dense-Qwen3-VL-Embedding.md"
repository: Major-TOM/EarthEmbeddingExplorer-Dense-Qwen3-VL-Embedding
chinese_name: "Explore global dense Earth embeddings with Qwen3-VL-Embedding"
last_updated: 2026-10-19
sdk_type: gradio
sdk_version: 5.49.1
downloads: 0
stars: 3
---

# EarthEmbeddingExplorer-Dense-Qwen3-VL-Embedding

> EarthEmbeddingExplorer-Dense-Qwen3-VL-Embedding - Major-TOM 在 ModelScope 创建的在线 Demo。Search 20.15 million global Sentinel-2 patches with Qwen3-VL: text, image and location retrieval, FP8 storage, adaptive GPU memory and multiscale maps.

Major-TOM/EarthEmbeddingExplorer-Dense-Qwen3-VL-Embedding 是 ModelScope 魔搭社区上的在线可交互 Demo（创空间），基于 gradio 5.49.1 构建，中文名为「Explore global dense Earth embeddings with Qwen3-VL-Embedding」。

- **Repository**: Major-TOM/EarthEmbeddingExplorer-Dense-Qwen3-VL-Embedding
- **SDK**: gradio
- **SDK version**: 5.49.1
- **Downloads**: 0
- **Stars**: 3
- **Last updated**: 2026-10-19

Source: https://www.modelscope.cn/studios/Major-TOM/EarthEmbeddingExplorer-Dense-Qwen3-VL-Embedding

---

# EarthEmbeddingExplorer Global · Qwen3-VL

Global text, RGB-image, text+image retrieval across **20,148,201** deduplicated Sentinel-2 patches. Public ModelScope Studio on xGPU (48 GB class / L20 requested).

Based on the layout and Qwen model wrapper of [EarthEmbeddingExplorer](https://modelscope.cn/studios/Major-TOM/EarthEmbeddingExplorer), Apache-2.0. Data: [Major-TOM/Core-S2RGB-Qwen3-VL-Embedding](https://modelscope.cn/datasets/Major-TOM/Core-S2RGB-Qwen3-VL-Embedding), CC BY-SA 4.0. Qwen3-VL-Embedding-2B supplies the query embeddings.

## Storage and startup

Only the 45 `embedding_fp8/part_*.parquet` files pinned in `source_files.json` are downloaded (35.063 GB compressed). Every download is size/SHA-256 checked. All pending shards are downloaded and verified first, using `max_workers=12`. Only after this download phase completes, each shard is streamed into FP8-byte memmaps plus inverse norms, coordinates and compressed metadata, then its download copy is removed. No original FP32 corpus is downloaded and no full-corpus FP16/FP32 matrix is materialized. The unpacked 2048-byte vector payload is about 41.26 GB; other metadata/model caches and staged source shards share the 100 GB disk budget. Free space is checked before downloading and unpacking. Completed shards resume after restart.

Startup prepares the full FP8 corpus in a background thread while the web server serves the map. Searches return a clear initialization error until the full index is ready. Completed shards resume from the persistent cache. `/mnt/workspace/eee-global/` holds the cache; configure `EEE_CACHE_DIR` to relocate it. A changed source manifest gets an isolated cache directory; old revisions must be removed deliberately before a new version if disk is limited.

## Agentic Search (default entry)

The first and explicitly selected tab is **Agentic Search**. It uses the official DeepSeek
`deepseek-flash` API alias (DeepSeek-V4.1-Flash-1017 as of 2026-10-18) to translate a natural
language request into a concise visual retrieval prompt in the same language, criteria, and
an optional approximate geographic bounding box. Bounds filter patch centres before global
Top-K ranking; they are not exact country or continent boundaries. Original Text, Image and
Text + Image tabs remain available.

After retrieval, the original Top 10 patches are downloaded and sent together in one
multimodal DeepSeek request. The original user request, planned visual criteria, immutable
rank, coordinates and acquisition date accompany each patch. The UI shows match, not-match
or uncertain assessments, concise visible features and structured JSON. The Explanation column and limitation paragraphs are omitted. Failed image
downloads retain their original ranks and are explicitly marked not verified. Retry downloads
automatically repeats verification for Agentic Search using the stored original request.
Plan subtitles repeat the original user request; plan labels, prompts, criteria, verification labels and natural-language answers use the request language. The examples include “Find global sea ice” and “检索沙漠和绿洲的交界的地区，用来做荒漠化监测研究”. An upstream API failure preserves retrieved results and previews. Existing non-agent search
tabs do not call DeepSeek. Model assessments are not ground truth; single-image causality,
change and global extent claims must remain qualified.

Configure **DEEPSEEK_API_KEY** as a Studio secret (never a plaintext variable or source-code
constant). Calls go from the server to `https://api.deepseek.com/chat/completions`, with JSON
output enabled and thinking disabled. Requests have bounded output, a 120-second timeout,
and at most one retry for HTTP 429/5xx. No API keys or base64 image payloads are returned to
the browser or written to request metrics. The UI discloses transmission of the request and
Top 10 previews to DeepSeek. API model aliases may be updated upstream over time.

## Search

The model uses BF16 on CUDA. After model load/warmup, GPU free memory is measured and 1.5 GiB is reserved for query activations and working buffers (`EEE_GPU_RESERVE_GIB`). GPU placement defaults to at most 17 million rows (`EEE_GPU_MAX_ROWS`), leaving the remaining rows on CPU after a 48 GiB instance stalled near its memory limit. Both portions are searched exhaustively and merged by score. Set `EEE_REQUIRE_ALL_GPU=1` for an all-GPU attempt when sufficient memory exists. Fused FP8 decoding/FP32 accumulation is validated before use. The original per-row positive scale cancels in cosine similarity. Inverse norms always refer to the **decoded FP8** vectors, not the original unit-norm embeddings.

This is exhaustive cosine retrieval over the FP8 representation, not an ANN or subsample search. Runtime hardware, corpus size and actual GPU/CPU placement are exposed in the UI and `/healthz`.

## Map and imagery

The global map uses 2° density cells; zoomed views aggregate the actual visible corpus into at most 90×90 cells. The browser never receives 20 million points. Search maps display only requested top-K (maximum 2,000); aggregation never changes retrieval. Pan/zoom events are debounced and superseded fetches are cancelled. Longitude wrapping is supported.

The first 10 results show metadata in a scrollable table; all top-K coordinates/scores can be exported. Top-10 RGB patch previews are requested separately, fetched via HTTP Range from their provenance Parquets, identity-checked and cropped to the stored 384×384 pixel window. At most 256 compressed previews are cached. No complete satellite imagery archive is downloaded.

## Run and verify

Use the platform PyTorch/CUDA base image, install `requirements.txt`, run `python app.py` on port 7860. `EEE_SKIP_INIT=1 python app.py` starts the UI only for local smoke testing; do not set it in deployment.

`python -m pytest tests -q` checks FP8 cache round-trips/resume, physical-row metadata lookup, exact cosine ranking with self exclusion, and world/dateline aggregation. Live L20 kernel validation runs at initialization. First successful full-corpus search is the runtime acceptance gate, not just an HTTP 200.

## Attribution

EEE authors and contributors: https://github.com/OpenGeoScope/EarthEmbeddingExplorer . The `qwen_encoder.py` wrapper is adapted from EEE. Leaflet 1.9.4 is BSD-2-Clause (license in `static/LEAFLET-LICENSE`); terrain and satellite tiles are © Esri. Ocean shading and coastlines come from the public-domain Natural Earth physical dataset. Cite Major TOM, Qwen3-VL-Embedding and EEE as described in the dataset README.

## Retrieval latency and memory measurements

Startup runs complete text searches at Top-K 100, 500, 1000 and 2000, then 1024×1024 image and mixed-query warmups. This exercises actual GPU block shapes, GPU Top-K and metadata reads before accepting requests. It cannot prevent platform-level cold starts after idle suspension.

GPU per-block candidates stay on GPU, are merged to GPU Top-K, then transferred as two compact arrays. The global overview uses 6° cells at zoom 1–2, 3° at zoom 3, and 2° at zoom 4; finer viewport aggregation is used when zoomed in. This changes only the map display, not the search corpus.

`REQUEST_METRICS` logs and `/healthz` include encoding, GPU wall time (including transfer and any compilation), CUDA event elapsed time, global merge, metadata/result preparation, handler total, and PyTorch allocated/reserved peak VRAM. Handler totals exclude Gradio queue waiting before invocation and browser rendering. Query text and images are not logged. The latest 20 records appear in Runtime & data. All text/image/mixed warmups must pass before readiness.

The mobile layout stacks controls and map, uses responsive map/gallery sizing and horizontally scrollable tabs/results. Fractional map zoom values are accepted.

## Time-series imagery

Select a retrieved POI or its map marker to open time-series imagery. Annual (reference month) is the default: one observation per year, prioritizing the lowest known Sentinel-2 scene cloud cover. The list supports cloud-cover or date sorting; unknown cloud cover sorts last. Monthly and all-overpass modes remain available. Downloads contain RGB previews, georeferenced GeoTIFFs and source manifests from Microsoft Planetary Computer.