google/embeddinggemma-tuning-lab

1---2title: EmbeddingGemma Tuning Lab3short_description: Fine-tune EmbeddingGemma to understand your personal taste4emoji: 😻5colorFrom: green6colorTo: indigo7sdk: gradio8sdk_version: 5.49.19app_file: app.py10pinned: false11hf_oauth: true12hf_oauth_scopes:13 - manage-repos14license: apache-2.015---16 17# 🤖 EmbeddingGemma Tuning Lab: Fine-Tuning and Mood Reader18 19This project provides a set of tools to fine-tune EmbeddingGemma to understand your personal taste in Hacker News titles and then use it to score and rank new articles based on their "vibe."20 21It includes three main applications:221.  A **Gradio App** for interactive fine-tuning, evaluation, and real-time "vibe checks."232.  An interactive **Command-Line (CLI) App** for viewing and scrolling through the scored feed directly in your terminal.243.  A **Flask App** for a simple, deployable web "mood reader" that displays the live HN feed.25 26---27 28## ✨ Features29 30* **Interactive Fine-Tuning:** Use a Gradio interface to select your favorite Hacker News titles and fine-tune the `google/embeddinggemma-300m` model on your preferences.31* **Semantic Search Evaluation:** See the immediate impact of your training by comparing semantic search results before and after fine-tuning.32* **Data & Model Management:** Easily import additional training data, export the generated dataset, and download the fine-tuned model as a ZIP file.33* **Hacker News Similarity Check:** View the live Hacker News feed with each story scored and color-coded based on the current model's understanding of your taste.34* **Similarity Lamp:** Input any news title or text to get a real-time similarity score (its "vibe") against your personalized anchor.35* **Interactive CLI:** A terminal-based mood reader with color-coded output, scrolling, and live refresh capabilities.36* **Standalone Flask App:** A lightweight, read-only web app to continuously display the scored HN feed, perfect for simple deployment.37 38---39 40## 🔧 How It Works41 42The core idea is to measure the "vibe" of a news title by calculating the semantic similarity between its embedding and the embedding of a fixed anchor phrase, defined in `config.py` as **`MY_FAVORITE_NEWS`**.43 441.  **Embedding:** The `sentence-transformers` library is used to convert news titles and the anchor phrase into high-dimensional vectors (embeddings).452.  **Scoring:** The cosine similarity (or dot product on normalized embeddings) between a title's embedding and the anchor's embedding is calculated. A higher score means a better "vibe."463.  **Fine-Tuning:** The Gradio app generates a contrastive learning dataset from your selections.47    * **Positive Pairs:** (`MY_FAVORITE_NEWS`, `[A title you selected]`)48    * **Negative Pairs:** (`MY_FAVORITE_NEWS`, `[A title you did not select]`)494.  **Training:** The model is trained using `MultipleNegativesRankingLoss`, which fine-tunes it to pull the embeddings of your "favorite" titles closer to the anchor phrase and push the others away.50 51## 🚀 Getting Started52 53### 1. Prerequisites54* Python 3.12+55* Git56 57### 2. Installation58 59```bash60# Clone the repository61git clone https://huggingface.co/spaces/bebechien/news-vibe-checker62cd news-vibe-checker63 64# Create and activate a virtual environment (recommended)65python -m venv venv66source venv/bin/activate  # On Windows, use `venv\Scripts\activate`67 68# Install the required packages69pip install -r requirements.txt70````71 72### 3\. (Optional) Hugging Face Authentication73 74If you plan to use gated models or push your fine-tuned model to the Hugging Face Hub, you need to authenticate.75 76```bash77# Set your Hugging Face token as an environment variable78export HF_TOKEN="your_hf_token_here"79```80 81-----82 83## 🖥️ Running the Applications84 85You can run any of the three applications depending on your needs.86 87### Option A: Interactive Fine-Tuning (Gradio App)88 89This is the main application for creating and evaluating a personalized model.90 91**▶️ To run:**92 93```bash94python app.py95```96 97Navigate to the local URL provided (e.g., `http://127.0.0.1:7860`).98 99### Option B: Interactive Terminal Viewer (CLI App)100 101This app runs directly in your terminal, allowing you to quickly see and scroll through the scored Hacker News feed.102 103![image](cli.png)104 105**▶️ To run:**106 107```bash108python cli_mood_reader.py109```110 111**Interactive Controls:**112 113  * **[↑|↓]** arrow keys to scroll through the story list.114  * **[SPACE]** to refresh the feed with the latest stories.115  * **[q]** to quit the application.116 117You can also start it with options:118 119```bash120# Specify a different model from Hugging Face121python cli_mood_reader.py --model google/embeddinggemma-300m122 123# Show 10 stories per screen instead of the default 15124python cli_mood_reader.py --top 10125```126 127### Option C: Standalone Web Viewer (Flask App)128 129This app is a simple, read-only web page that fetches and displays the scored HN feed. It's ideal for deploying a finished model.130 131![image](flask.png)132 133**▶️ To run:**134 135```bash136# (Optional) Specify a model from the Hugging Face Hub137export MOOD_MODEL="bebechien/embedding-gemma-finetuned-hn"138 139# Run the Flask server140python flask_app.py141```142 143Navigate to `http://127.0.0.1:5000` to see the results.144 145-----146 147## ⚙️ Configuration148 149Key parameters can be adjusted in `config.py`:150 151  * `MODEL_NAME`: The base model to use for fine-tuning (e.g., `'google/embeddinggemma-300m'`).152  * `QUERY_ANCHOR`: The anchor text used for similarity scoring (e.g., `"MY_FAVORITE_NEWS"`).153  * `DEFAULT_MOOD_READER_MODEL`: The default model used by the Flask and CLI apps.154  * `HN_RSS_URL`: The RSS feed URL.155  * `CACHE_DURATION_SECONDS`: How long to cache the RSS feed data.156 157-----158 159## 📂 File Structure160 161```162.163├── app.py                  # Main Gradio application entry point164├── cli_mood_reader.py      # Interactive command-line mood reader165├── cli.png                 # Screenshot for CLI app166├── flask_app.py            # Standalone Flask application for mood reading167├── flask.png               # Screenshot for Flask app168├── src/                    # Source code for the application169│   ├── config.py           # Central configuration for all modules170│   ├── data_fetcher.py     # Fetches and caches the Hacker News RSS feed171│   ├── hn_mood_reader.py   # Core logic for fetching and scoring172│   ├── model_trainer.py    # Handles model loading and fine-tuning173│   ├── session_manager.py  # Manages user sessions and application state174│   ├── ui.py               # Defines the Gradio user interface175│   └── vibe_logic.py       # Calculates similarity scores and "vibe" status176├── requirements.txt        # Python package dependencies177├── example_training_dataset.csv # Example dataset for training178├── README.md               # This file179├── artifacts/              # Stores session-specific fine-tuned models and datasets (generated)180└── templates/              # HTML templates for the Flask app181    ├── index.html182    └── error.html183```184