LeCompute: EmbeddingGemma 2 local retrieval example

This archive contains original educational code and six constructed notes in
French and English. It is a functional example, not a representative benchmark,
a PDF/media parser, an inference server or a complete RAG application.

Python 3.13 is the reference interpreter. Create a virtual environment with
python -m venv .venv
Activate in PowerShell: .venv\Scripts\Activate.ps1
Activate in a POSIX shell: source .venv/bin/activate
Alternatively, use the virtual environment's Python executable directly.

Install matching CPU PyTorch and TorchVision first:
python -m pip install torch==2.15.0 torchvision==0.29.2 --index-url https://download.pytorch.org/whl/cpu
python -m pip install -r requirements.txt

Pillow and TorchVision are included because the tested Transformers processor
imports image/video preprocessing classes even when the model's vision and
audio encoders are disabled.

French:
python local_search.py index --documents example_fr.json --index index-fr.npz
python local_search.py search --index index-fr.npz --offline --query "Comment rechercher mes documents sans les envoyer sur Internet ?"

English:
python local_search.py index --documents example_en.json --index index-en.npz
python local_search.py search --index index-en.npz --offline --query "How can I search my documents without sending them online?"

The first model load downloads public model files into the Hugging Face cache.
It does not send the corpus to an inference endpoint. Once files are cached,
--offline prevents Hugging Face Hub model lookups. Keep your chosen packages,
model files and index available to run without a network connection.

The model is google/embeddinggemma-2, revision
f9972ac22e696a105c482202646979e33e4b5a1e, text only, CPU FP32, four PyTorch threads.
Default output size is 256 dimensions. Use --dimensions 128/512/768 during
index creation to choose another supported size. Queries inherit the saved
index dimension. Model id, revision and prompt formatting must match.

FP16 is not suitable for this model's activation range. The script uses FP32.
Document vectors and query vectors are normalized. The dot product ranks the
short corpus by cosine similarity; scores are not confidence probabilities.
Long passages are rejected rather than silently truncated. Input JSON needs
unique id, title and text strings for every passage.

Search commands reload the model and index. Internal load, encoding and ranking
timings exclude Python imports and index reading. Time the whole command if
you need end-to-end execution cost; keep a model resident for a real service.
The index stores passage text as well as vectors and a manifest. Protect it
as you would the underlying documents.

FR : cet exemple explique la separation entre l'indexation et la recherche.
Les six notes sont pedagogiques et ne permettent pas d'affirmer qu'un modele
est meilleur qu'un autre. Les resultats de recherche sont des passages classes,
sans generation de reponse. Les poids et dependances se telechargent au premier
lancement ; le mode --offline reutilise ensuite le cache local.

Official model and instructions:
https://huggingface.co/google/embeddinggemma-2
https://ai.google.dev/gemma/docs/embeddinggemma/inference-embeddinggemma-with-sentence-transformers
