|
|
--- |
|
|
title: EmbeddingGemma Tuning Lab |
|
|
short_description: Fine-tune EmbeddingGemma to understand your personal taste |
|
|
emoji: 😻 |
|
|
colorFrom: green |
|
|
colorTo: indigo |
|
|
sdk: gradio |
|
|
sdk_version: 5.49.1 |
|
|
app_file: app.py |
|
|
pinned: false |
|
|
hf_oauth: true |
|
|
hf_oauth_scopes: |
|
|
- manage-repos |
|
|
license: apache-2.0 |
|
|
--- |
|
|
|
|
|
# 🤖 EmbeddingGemma Tuning Lab: Fine-Tuning and Mood Reader |
|
|
|
|
|
This 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." |
|
|
|
|
|
It includes three main applications: |
|
|
1. A **Gradio App** for interactive fine-tuning, evaluation, and real-time "vibe checks." |
|
|
2. An interactive **Command-Line (CLI) App** for viewing and scrolling through the scored feed directly in your terminal. |
|
|
3. A **Flask App** for a simple, deployable web "mood reader" that displays the live HN feed. |
|
|
|
|
|
--- |
|
|
|
|
|
## ✨ Features |
|
|
|
|
|
* **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. |
|
|
* **Semantic Search Evaluation:** See the immediate impact of your training by comparing semantic search results before and after fine-tuning. |
|
|
* **Data & Model Management:** Easily import additional training data, export the generated dataset, and download the fine-tuned model as a ZIP file. |
|
|
* **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. |
|
|
* **Similarity Lamp:** Input any news title or text to get a real-time similarity score (its "vibe") against your personalized anchor. |
|
|
* **Interactive CLI:** A terminal-based mood reader with color-coded output, scrolling, and live refresh capabilities. |
|
|
* **Standalone Flask App:** A lightweight, read-only web app to continuously display the scored HN feed, perfect for simple deployment. |
|
|
|
|
|
--- |
|
|
|
|
|
## 🔧 How It Works |
|
|
|
|
|
The 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`**. |
|
|
|
|
|
1. **Embedding:** The `sentence-transformers` library is used to convert news titles and the anchor phrase into high-dimensional vectors (embeddings). |
|
|
2. **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." |
|
|
3. **Fine-Tuning:** The Gradio app generates a contrastive learning dataset from your selections. |
|
|
* **Positive Pairs:** (`MY_FAVORITE_NEWS`, `[A title you selected]`) |
|
|
* **Negative Pairs:** (`MY_FAVORITE_NEWS`, `[A title you did not select]`) |
|
|
4. **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. |
|
|
|
|
|
## 🚀 Getting Started |
|
|
|
|
|
### 1. Prerequisites |
|
|
* Python 3.12+ |
|
|
* Git |
|
|
|
|
|
### 2. Installation |
|
|
|
|
|
```bash |
|
|
# Clone the repository |
|
|
git clone https://huggingface.co/spaces/bebechien/news-vibe-checker |
|
|
cd news-vibe-checker |
|
|
|
|
|
# Create and activate a virtual environment (recommended) |
|
|
python -m venv venv |
|
|
source venv/bin/activate # On Windows, use `venv\Scripts\activate` |
|
|
|
|
|
# Install the required packages |
|
|
pip install -r requirements.txt |
|
|
```` |
|
|
|
|
|
### 3\. (Optional) Hugging Face Authentication |
|
|
|
|
|
If you plan to use gated models or push your fine-tuned model to the Hugging Face Hub, you need to authenticate. |
|
|
|
|
|
```bash |
|
|
# Set your Hugging Face token as an environment variable |
|
|
export HF_TOKEN="your_hf_token_here" |
|
|
``` |
|
|
|
|
|
----- |
|
|
|
|
|
## 🖥️ Running the Applications |
|
|
|
|
|
You can run any of the three applications depending on your needs. |
|
|
|
|
|
### Option A: Interactive Fine-Tuning (Gradio App) |
|
|
|
|
|
This is the main application for creating and evaluating a personalized model. |
|
|
|
|
|
**▶️ To run:** |
|
|
|
|
|
```bash |
|
|
python app.py |
|
|
``` |
|
|
|
|
|
Navigate to the local URL provided (e.g., `http://127.0.0.1:7860`). |
|
|
|
|
|
### Option B: Interactive Terminal Viewer (CLI App) |
|
|
|
|
|
This app runs directly in your terminal, allowing you to quickly see and scroll through the scored Hacker News feed. |
|
|
|
|
|
 |
|
|
|
|
|
**▶️ To run:** |
|
|
|
|
|
```bash |
|
|
python cli_mood_reader.py |
|
|
``` |
|
|
|
|
|
**Interactive Controls:** |
|
|
|
|
|
* **[↑|↓]** arrow keys to scroll through the story list. |
|
|
* **[SPACE]** to refresh the feed with the latest stories. |
|
|
* **[q]** to quit the application. |
|
|
|
|
|
You can also start it with options: |
|
|
|
|
|
```bash |
|
|
# Specify a different model from Hugging Face |
|
|
python cli_mood_reader.py --model google/embeddinggemma-300m |
|
|
|
|
|
# Show 10 stories per screen instead of the default 15 |
|
|
python cli_mood_reader.py --top 10 |
|
|
``` |
|
|
|
|
|
### Option C: Standalone Web Viewer (Flask App) |
|
|
|
|
|
This app is a simple, read-only web page that fetches and displays the scored HN feed. It's ideal for deploying a finished model. |
|
|
|
|
|
 |
|
|
|
|
|
**▶️ To run:** |
|
|
|
|
|
```bash |
|
|
# (Optional) Specify a model from the Hugging Face Hub |
|
|
export MOOD_MODEL="bebechien/embedding-gemma-finetuned-hn" |
|
|
|
|
|
# Run the Flask server |
|
|
python flask_app.py |
|
|
``` |
|
|
|
|
|
Navigate to `http://127.0.0.1:5000` to see the results. |
|
|
|
|
|
----- |
|
|
|
|
|
## ⚙️ Configuration |
|
|
|
|
|
Key parameters can be adjusted in `config.py`: |
|
|
|
|
|
* `MODEL_NAME`: The base model to use for fine-tuning (e.g., `'google/embeddinggemma-300m'`). |
|
|
* `QUERY_ANCHOR`: The anchor text used for similarity scoring (e.g., `"MY_FAVORITE_NEWS"`). |
|
|
* `DEFAULT_MOOD_READER_MODEL`: The default model used by the Flask and CLI apps. |
|
|
* `HN_RSS_URL`: The RSS feed URL. |
|
|
* `CACHE_DURATION_SECONDS`: How long to cache the RSS feed data. |
|
|
|
|
|
----- |
|
|
|
|
|
## 📂 File Structure |
|
|
|
|
|
``` |
|
|
. |
|
|
├── app.py # Main Gradio application entry point |
|
|
├── cli_mood_reader.py # Interactive command-line mood reader |
|
|
├── cli.png # Screenshot for CLI app |
|
|
├── flask_app.py # Standalone Flask application for mood reading |
|
|
├── flask.png # Screenshot for Flask app |
|
|
├── src/ # Source code for the application |
|
|
│ ├── config.py # Central configuration for all modules |
|
|
│ ├── data_fetcher.py # Fetches and caches the Hacker News RSS feed |
|
|
│ ├── hn_mood_reader.py # Core logic for fetching and scoring |
|
|
│ ├── model_trainer.py # Handles model loading and fine-tuning |
|
|
│ ├── session_manager.py # Manages user sessions and application state |
|
|
│ ├── ui.py # Defines the Gradio user interface |
|
|
│ └── vibe_logic.py # Calculates similarity scores and "vibe" status |
|
|
├── requirements.txt # Python package dependencies |
|
|
├── example_training_dataset.csv # Example dataset for training |
|
|
├── README.md # This file |
|
|
├── artifacts/ # Stores session-specific fine-tuned models and datasets (generated) |
|
|
└── templates/ # HTML templates for the Flask app |
|
|
├── index.html |
|
|
└── error.html |
|
|
``` |
|
|
|
