# Delete dataset by ID
Source: https://facetai.mintlify.app/api-reference/dataset/delete-dataset

DELETE /datasets/{processed_dataset_id}
Delete a dataset and all associated files using its unique processed dataset ID.
NOTE: This only deletes preprocessed dataset, NOT raw dataset files!



# Get dataset by ID
Source: https://facetai.mintlify.app/api-reference/dataset/get-dataset

GET /datasets/{processed_dataset_id}
Get information about a dataset using its unique processed dataset ID.



# Get all datasets
Source: https://facetai.mintlify.app/api-reference/dataset/get-datasets

GET /datasets
Get information about all the processed datasets owned by the user.



# Health
Source: https://facetai.mintlify.app/api-reference/dataset/health

GET /health



# Process dataset
Source: https://facetai.mintlify.app/api-reference/dataset/process-dataset

POST /datasets/process
Process a dataset into ChatML format

The processing converts the dataset to ChatML format using the provided configuration.
The configuration can include field mappings that specify either direct column mappings or template strings
with column references.

Example field mappings:
```python
{
    "system_field": {"type": "template", "value": "You are a helpful assistant."},
    "user_field": {"type": "column", "value": "question"},
    "assistant_field": {"type": "template", "value": "Answer: {answer}"}
}
```



# Upload dataset
Source: https://facetai.mintlify.app/api-reference/dataset/upload-dataset

POST /datasets/upload
Upload a dataset file to storage



# Create Export
Source: https://facetai.mintlify.app/api-reference/export/create-export

POST /exports



# Get Export
Source: https://facetai.mintlify.app/api-reference/export/get-export

GET /exports/{job_id}



# Get Exports
Source: https://facetai.mintlify.app/api-reference/export/get-exports

GET /exports



# Health
Source: https://facetai.mintlify.app/api-reference/export/health

GET /health



# Batch inference
Source: https://facetai.mintlify.app/api-reference/inference/batch-inference

POST /inference/batch
Run batch inference using a trained model



# Evaluation
Source: https://facetai.mintlify.app/api-reference/inference/evaluation

POST /evaluation
Run evaluation of a fine-tuned model on a dataset



# Health
Source: https://facetai.mintlify.app/api-reference/inference/health

GET /health



# Inference
Source: https://facetai.mintlify.app/api-reference/inference/inference

POST /inference
Run inference using a trained model



# Introduction
Source: https://facetai.mintlify.app/api-reference/introduction

API reference for the Gemma Facet cloud services

<Note>
  This page is still in development. We do not recommend using this page as a source of truth for the API endpoints.
</Note>

## Welcome

There are two ways to build API documentation: [OpenAPI](https://mintlify.com/docs/api-playground/openapi/setup) and [MDX components](https://mintlify.com/docs/api-playground/mdx/configuration). For the starter kit, we are using the following OpenAPI specification.

<Card title="Plant Store Endpoints" icon="leaf" href="https://github.com/mintlify/starter/blob/main/api-reference/openapi.json">
  View the OpenAPI specification file
</Card>

## Authentication

All API endpoints are authenticated using Bearer tokens and picked up from the specification file.

```json  theme={null}
"security": [
  {
    "bearerAuth": []
  }
]
```


# Delete job by ID
Source: https://facetai.mintlify.app/api-reference/training/delete-job

DELETE /jobs/{job_id}
Delete a job and all associated GCS resources.
This includes the job metadata, config file, adapter/merged model, and GGUF file if available.



# Download model
Source: https://facetai.mintlify.app/api-reference/training/download-model

GET /jobs/download/{job_id}
Generate a signed URL for downloading the GGUF file of a specific job.
This is a convenience endpoint that automatically finds the GGUF file path from job status.



# Get job by ID
Source: https://facetai.mintlify.app/api-reference/training/get-job

GET /jobs/{job_id}



# Jobs
Source: https://facetai.mintlify.app/api-reference/training/get-jobs

GET /jobs
List all jobs with job_id and job_name.



# Health
Source: https://facetai.mintlify.app/api-reference/training/health

GET /health



# Train model
Source: https://facetai.mintlify.app/api-reference/training/train

POST /train



# Preprocessing Guide
Source: https://facetai.mintlify.app/dataset/datasets

Complete guide to uploading, processing, and managing datasets in Facet

This guide walks you through everything you need to know about working with datasets in Facet, from uploading your data to configuring field mappings and processing options.

## Using Hugging Face Datasets

We recommend using datasets from the [Hugging Face Hub](https://huggingface.co/datasets) for easy integration and management.
If your data requirement is not supported by our platform or custom upload, you can preprocess manually and upload to Hugging Face Hub first.

Import datasets directly from Hugging Face Hub using their repository name:

```text  theme={null}
Examples to try:
- microsoft/DialoGPT-medium
- HuggingFaceH4/ultrachat_200k
- tatsu-lab/alpaca
```

<Steps>
  <Step title="Find a Dataset">
    Browse [Hugging Face Datasets](https://huggingface.co/datasets) to find one that fits your needs.

    <Tip>
      Look for datasets with conversation or instruction-following formats for best results.
    </Tip>
  </Step>

  <Step title="Copy the Repository Name">
    Use the format `organization/dataset-name` from the dataset page.

    <Note>
      You don't need to include the full URL, just the repository identifier.
    </Note>
  </Step>

  <Step title="Select Subset and Split">
    If the dataset has multiple subsets, choose the one you want to use.

    <Check>
      Common subsets include "train", "test", "validation", or specific task names.
    </Check>
  </Step>
</Steps>

## Uploading Your Dataset

We are working on expanding this service to handle unstructured documents with LLM-based synthesis.

### Supported File Formats

Facet supports a wide range of data formats for maximum flexibility:

<CardGroup cols={2}>
  <Card title="CSV Files" icon="file-text">
    **Best for**: Structured data, spreadsheets, tabular data

    * Comma-separated values
    * Headers in first row
    * UTF-8 encoding recommended
  </Card>

  <Card title="JSON/JSONL" icon="code">
    **Best for**: Conversational data, complex structures - JSON: Single object
    with array of examples - JSONL: One JSON object per line - Nested structures
    supported
  </Card>

  <Card title="Parquet" icon="database">
    **Best for**: Large datasets, efficient storage - Columnar format - Fast
    loading and processing - Compressed storage
  </Card>

  <Card title="Excel Files" icon="table">
    **Best for**: Business data, multiple sheets

    * .xlsx and .xls formats
    * Multiple sheets supported
    * First sheet used by default
  </Card>
</CardGroup>

### File Size Limits

* **Maximum file size**: 100MB per upload
* **Recommended size**: 10-50MB for optimal processing speed
* **Large datasets**: Consider splitting into multiple files or using Hugging Face Hub

<Warning>
  Very large files may take longer to process. Consider using Hugging Face Hub
  for datasets over 100MB.
</Warning>

## Configuring Field Mappings

Field mappings tell Facet how to transform your data into the conversational format needed for training.

### Understanding Field Types

In the dropdown menus for field selection, you will see three types of fields:

<Tabs>
  <Tab title="Template Fields">
    **Use for**: Static text, instructions, prompts

    ```json  theme={null}
    {
      "type": "template",
      "value": "You are a helpful assistant. Answer the following question:"
    }
    ```

    <Note>
      Template fields use fixed text that doesn't change between examples.
    </Note>
  </Tab>

  <Tab title="Column Fields">
    **Use for**: Data from your dataset columns

    ```json  theme={null}
    {
      "type": "column", 
      "value": "question"
    }
    ```

    <Check>
      Column fields pull data directly from your dataset's columns.
    </Check>
  </Tab>

  <Tab title="Image Fields">
    **Use for**: Images in your dataset

    ```json  theme={null}
    {
      "type": "image",
      "value": "image_column"
    }
    ```

    <Tip>
      Images are automatically processed and can be included in user messages.
    </Tip>
  </Tab>
</Tabs>

## Processing Modes Explained

### Language Modeling Mode

**Best for**: General conversation, instruction following, text generation

This mode creates conversations with three roles:

* **System**: Instructions or context for the model
* **User**: Questions, prompts, or input from the user
* **Assistant**: Model's responses

### Prompt-Only Mode

**Best for**: Reasoning tasks, math problems, structured thinking

This mode creates prompts without assistant responses, perfect for GRPO training where the model learns to reason step-by-step.

### Preference Tuning Mode

**Best for**: Aligning models with human preferences, RLHF

This mode creates data with chosen and rejected responses for preference-based training algorithms.

## Data Augmentation

We are working on expanding this!

## Next Steps

Once your dataset is processed and ready:

1. **Start Training**: Use your processed dataset to fine-tune a Gemma model
2. **Review Results**: Check the training progress and evaluation metrics
3. **Export Model**: Download your fine-tuned model in various formats
4. **Deploy**: Set up your model for production use

Ready to start training? Head to the [Fine-tuning guide](/fine-tuning/introduction) to learn how to train your model.


# Preprocessing Workflow
Source: https://facetai.mintlify.app/dataset/introduction

Prepare and format your datasets for fine-tuning Gemma models with Facet's preprocessing service

Turn raw text or multimodal data into training‑ready conversations in a few steps. You can upload files (CSV, JSON/JSONL, Parquet, Excel) or import from Hugging Face, and optionally include images for vision‑language tasks. Choose a processing mode that matches your objective (language modeling, prompt‑only, or preference tuning) and produce a clean, consistent dataset for training.

<Steps>
  <Step title="Pick your data source">
    Upload a file or import a Hugging Face dataset by repository name.

    <Note>
      Supports text and image data for multimodal training.
    </Note>
  </Step>

  <Step title="Map fields to roles">
    Point columns/keys to conversation roles (system, user, assistant) or to chosen/rejected pairs for preference data.
  </Step>

  <Step title="Choose processing mode">
    Select Language Modeling, Prompt‑only, or Preference Tuning to shape the output format.
  </Step>

  <Step title="Preview and validate">
    Inspect a sample of the processed dataset and fix any mapping issues.

    <Check>
      Confirm examples look correct before running the full job.
    </Check>
  </Step>

  <Step title="Process and version">
    Run the job to generate a training‑ready dataset you can reuse across experiments.
  </Step>
</Steps>

Next: open the [Datasets page](/dataset/datasets.mdx) to create your first processed dataset.


# Deploy Facet AI
Source: https://facetai.mintlify.app/deployment

Deploy Facet AI on your own cloud infrastructure for production use

## Overview

Deploying Facet AI on your own infrastructure gives you complete control over your fine-tuning platform, data, and costs. This guide covers deploying both the backend services and frontend application.

<Warning>
  **Production Deployment**: This deployment is recommended for production use, enterprise customers, or when you need full control over your infrastructure.
</Warning>

## Architecture

Facet AI consists of two main components:

<CardGroup cols={2}>
  <Card title="Cloud Services" icon="server">
    * Dataset preprocessing microservice
    * Training orchestration microservice
    * Training, inference, evaluation GPU workers
    * Model export service
    * API Gateway for unified access
  </Card>

  <Card title="Frontend Application" icon="desktop">
    * Next.js web application
    * User authentication and dashboard
    * Model management interface
    * Real-time training monitoring
  </Card>
</CardGroup>

## Prerequisites

<Steps>
  <Step title="Google Cloud Platform Setup">
    <Tabs>
      <Tab title="Create GCP Project">
        1. Go to [Google Cloud Console](https://console.cloud.google.com)
        2. Create a new project or select an existing one
        3. Note your project ID for later use
        4. Enable billing on your project

        <Warning>
          Some APIs require billing to be enabled. Make sure billing is active before deployment.
        </Warning>
      </Tab>

      <Tab title="Install Required Tools">
        Install the required CLI tools. Use the official install guides for your OS when in doubt.

        ```bash  theme={null}
        # macOS (Homebrew)
        brew install terraform
        brew install --cask google-cloud-sdk

        # Debian/Ubuntu (apt)
        # See https://www.terraform.io/downloads and https://cloud.google.com/sdk/docs/install
        sudo apt-get update && sudo apt-get install -y terraform
        # Follow GCP docs to install the Cloud SDK for your distro
        ```

        Refer to the official docs for other platforms:

        * Terraform: [https://www.terraform.io/downloads](https://www.terraform.io/downloads)
        * Google Cloud CLI: [https://cloud.google.com/sdk/docs/install](https://cloud.google.com/sdk/docs/install)
      </Tab>
    </Tabs>
  </Step>

  <Step title="Authentication Setup">
    1. Authenticate with Google Cloud:
       ```bash  theme={null}
       gcloud auth login
       gcloud auth application-default login
       ```

    2. Set your project:
       ```bash  theme={null}
       gcloud config set project YOUR_PROJECT_ID
       ```

    3. Verify you have the correct permissions (Owner or Editor role)

    <Check>
      Verify setup with: `gcloud auth list` and `gcloud config get-value project`
    </Check>
  </Step>
</Steps>

<Note>
  Our Terraform IaC includes both production and staging setups. The staging workspace is intended mainly for development and testing; see the [staging section](#staging) for details.
</Note>

## Deploy Backend Services

<Steps>
  <Step title="Clone and Setup">
    1. Clone the cloud services repository:
       ```bash  theme={null}
       git clone https://github.com/gemma-facet/cloud-services
       cd cloud-services/infrastructure
       ```

    2. Copy and edit the configuration files for your environment:
       ```bash  theme={null}
       cp environments/staging.tfvars.example environments/staging.tfvars
       cp environments/production.tfvars.example environments/production.tfvars
       ```

    3. Edit `terraform.tfvars` or the appropriate `*.tfvars` with your project details:
       ```hcl  theme={null}
       project_id = "your-project-id"
       region = "us-central1"
       ```
  </Step>

  <Step title="Initialize and Deploy">
    Use our automated deployment script:

    ```bash  theme={null}
    make init ENV=production
    make full-deploy ENV=production
    make output ENV=production
    ```

    <Info>
      The `make full-deploy` command performs these steps automatically:

      1. Deploy core infrastructure (APIs, IAM, Artifact Registry, Storage, Firebase, networking)
      2. Build and push Docker images to Artifact Registry
      3. Deploy microservices and configure networking (Cloud Run and API Gateway)
    </Info>

    <Tip>
      Expect the deployment to take \~15-30 minutes depending on region and project size. The process runs unattended in most cases.
    </Tip>
  </Step>

  <Warning>
    Our IaC configures Firebase authentication (email/password) for you so the frontend can run out of the box. It does not enable Google OAuth by default. To add Google sign-in, go to Firebase Console → Authentication → Sign-in method and enable Google.
  </Warning>
</Steps>

## Deploy Frontend Application

<Steps>
  <Step title="Clone Frontend Repository">
    ```bash  theme={null}
    git clone https://github.com/gemma-facet/frontend-ui
    cd frontend-ui
    ```
  </Step>

  <Step title="Configure Environment Variables">
    1. Copy the example environment file:
       ```bash  theme={null}
       cp .env.example .env
       ```

    2. Fill in the environment variables from your backend deployment:
       ```bash  theme={null}
       # From terraform output
       INFERENCE_SERVICE_URL=https://your-inference-service-url
       API_GATEWAY_URL=https://your-api-gateway-url

       # Also from terraform output
       NEXT_PUBLIC_FIREBASE_API_KEY=your-firebase-api-key
       NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project-id.firebaseapp.com
       NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
       NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project-id.appspot.com
       NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your-messaging-sender-id
       NEXT_PUBLIC_FIREBASE_APP_ID=your-firebase-app-id
       ```
  </Step>

  <Step title="Running the Frontend">
    <Tabs>
      <Tab title="Run Locally">
        We recommend using `bun` for development, but `npm` or `yarn` also work.

        ```bash  theme={null}
        npm run install
        npm run build
        npm run start
        ```

        <Tip>
          Access the app at `http://localhost:3000` in your browser.
        </Tip>
      </Tab>

      <Tab title="Deploy to Vercel">
        ```bash  theme={null}
        # Install Vercel CLI
        npm i -g vercel

        # Deploy
        vercel deploy --prod
        ```

        <Tip>
          Vercel provides automatic deployments from GitHub and excellent performance for Next.js applications.
        </Tip>
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Infrastructure Management

### Available Commands

<AccordionGroup>
  <Accordion title="Deployment Commands">
    ```bash  theme={null}
    make init           # Initialize Terraform
    make check          # Validate configuration
    make full-deploy    # Complete deployment workflow
    make deploy-core    # Deploy core infrastructure only
    make deploy-services # Deploy microservices only
    ```
  </Accordion>

  <Accordion title="Management Commands">
    ```bash  theme={null}
    make plan           # Plan infrastructure changes
    make output         # Show deployment outputs
    make destroy        # Destroy all infrastructure
    make help           # Show all available commands
    ```
  </Accordion>

  <Accordion title="Build Commands">
    ```bash  theme={null}
    make build          # Build all containers
    make deploy         # Deploy infrastructure only
    ```
  </Accordion>
</AccordionGroup>

### Staging

The staging workspace in the Terraform setup is mainly intended for development and testing. If you'd like a staging environment for your own development, follow the guide in our repo to set up a staging workspace in three commands: [https://github.com/gemma-facet/cloud-services/tree/main/infrastructure](https://github.com/gemma-facet/cloud-services/tree/main/infrastructure)

<Note>
  Running `npm run dev` in the frontend will automatically connect to the staging backend since we use Next.js environment variables to differentiate between staging and production. You can manually edit this by changing the `.env` file.
</Note>

### Infrastructure Components

<CardGroup cols={2}>
  <Card title="Core Infrastructure" icon="building">
    * Google Cloud APIs and IAM roles
    * Artifact Registry for container images
    * Service accounts and permissions
  </Card>

  <Card title="Storage Layer" icon="database">
    * Google Cloud Storage buckets
    * Firestore database for metadata
    * Persistent disk volumes
  </Card>

  <Card title="Compute Services" icon="server">
    * Cloud Run services for microservices
    * Cloud Build for container building
    * Cloud Scheduler for batch jobs
  </Card>

  <Card title="Networking" icon="network-wired">
    * API Gateway for unified access
    * VPC and firewall rules
    * Load balancing and SSL certificates
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Deployment Issues">
    **Terraform errors:**

    * Ensure you have Owner/Editor role on the GCP project
    * Check that billing is enabled
    * Verify all required APIs are enabled

    **Authentication errors:**

    * Run `gcloud auth application-default login`
    * Set quota project: `gcloud auth application-default set-quota-project YOUR_PROJECT_ID`
  </Accordion>

  <Accordion title="Service Issues">
    **Cloud Run services not starting:**

    * Check container logs in Cloud Console
    * Verify environment variables are set correctly
    * Ensure service account has proper permissions

    **Firebase authentication not working:**

    * Enable Google sign-in in Firebase Console
    * Verify OAuth client configuration
    * Check Firebase config in frontend environment variables
  </Accordion>

  <Accordion title="Resource Conflicts">
    **Resources already exist:**

    ```bash  theme={null}
    # Import existing resources to Terraform
    terraform import module.compute.google_cloud_run_v2_service.preprocessing_service \
      projects/YOUR_PROJECT_ID/locations/us-central1/services/preprocessing-service
    ```
  </Accordion>
</AccordionGroup>

<Note>
  **Need help with deployment?** Check our [GitHub repository](https://github.com/gemma-facet/cloud-services) for the latest updates and open an issue if you encounter problems.
</Note>


# Model Deployment Guide
Source: https://facetai.mintlify.app/deployment/deployment

Deploy your fine-tuned models for production use with various deployment options

Once your model is trained and evaluated, it's time to deploy it for production use. This guide covers multiple deployment options from local development to cloud production.

## Deployment Options

<CardGroup cols={2}>
  <Card title="Local Deployment" icon="laptop">
    Run models on your local machine for development and testing
  </Card>

  <Card title="Cloud Deployment" icon="cloud">
    Deploy on cloud platforms for production use
  </Card>

  <Card title="Container Deployment" icon="package">
    Use Docker containers for consistent deployment
  </Card>

  <Card title="Serverless Deployment" icon="zap">
    Deploy on serverless platforms for cost efficiency
  </Card>
</CardGroup>

## Local Deployment

### GGUF Format (Recommended for Local)

GGUF models are optimized for CPU inference and work well for local deployment. First, download your model in GGUF format from the Facet AI platform.

#### Using llama.cpp

**Installation**:

```bash  theme={null}
# Clone and build llama.cpp
git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp
make
```

**Running your model**:

```bash  theme={null}
# Basic inference
./llama-cli -m path/to/your/model.gguf -p "Your prompt here"

# With system prompt
./llama-cli -m path/to/your/model.gguf -sys "You are a helpful assistant." -p "What is the capital of France?"

# Interactive mode
./llama-cli -m path/to/your/model.gguf -i
```

**Advanced options**:

```bash  theme={null}
# Control generation parameters
./llama-cli -m model.gguf -p "Your prompt" --temp 0.7 --top-k 40 --top-p 0.9

# Use GPU acceleration (if available)
./llama-cli -m model.gguf -p "Your prompt" --gpu-layers 20
```

#### Using Ollama

**Installation**:

```bash  theme={null}
# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh
```

**Create a Modelfile**:

```dockerfile  theme={null}
FROM path/to/your/model.gguf

SYSTEM """
You are a helpful assistant specialized in answering questions about geography.
"""

PARAMETER temperature 0.7
PARAMETER top_k 40
PARAMETER top_p 0.9
```

**Deploy your model**:

```bash  theme={null}
# Create the model
ollama create my-geography-assistant -f Modelfile

# Run the model
ollama run my-geography-assistant

# If model is on Hugging Face Hub
ollama run hf.co/username/model-name:q8_0
```

**API usage**:

```bash  theme={null}
# Start Ollama server
ollama serve

# Make API calls
curl http://localhost:11434/api/generate -d '{
  "model": "my-geography-assistant",
  "prompt": "What is the capital of France?",
  "stream": false
}'
```

### HuggingFace Transformers (Python)

For more control and integration with Python applications:

```python  theme={null}
from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

# Load your fine-tuned model
model_name = "username/your-fine-tuned-model"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype=torch.float16,
    device_map="auto"
)

# Generate responses
def generate_response(prompt, max_length=100):
    inputs = tokenizer(prompt, return_tensors="pt")
    with torch.no_grad():
        outputs = model.generate(
            **inputs,
            max_length=max_length,
            temperature=0.7,
            do_sample=True,
            pad_token_id=tokenizer.eos_token_id
        )
    return tokenizer.decode(outputs[0], skip_special_tokens=True)

# Example usage
response = generate_response("What is the capital of France?")
print(response)
```

## Cloud Deployment

Cloud deployment is purely experiment for now, will expand in future.

### Google Cloud Run (vLLM)

Deploy your model on Google Cloud Run using vLLM for high-performance inference.

#### Prerequisites

* Google Cloud Project with billing enabled
* Docker installed locally
* Google Cloud SDK installed

#### Step 1: Prepare Your Model

Export your model in merged format and upload to Google Cloud Storage:

```bash  theme={null}
# Upload your model to GCS
gsutil cp -r your-model-directory gs://your-bucket/models/
```

#### Step 2: Create Dockerfile

```dockerfile  theme={null}
FROM vllm/vllm-openai:latest

# Copy your model
COPY model/ /app/model/

# Set environment variables
ENV MODEL_NAME=your-model-name
ENV MODEL_PATH=/app/model
ENV HOST=0.0.0.0
ENV PORT=8000

# Expose port
EXPOSE 8000

# Start the server
CMD ["python", "-m", "vllm.entrypoints.openai.api_server", \
     "--model", "/app/model", \
     "--host", "0.0.0.0", \
     "--port", "8000"]
```

#### Step 3: Build and Deploy

```bash  theme={null}
# Build the container
gcloud builds submit --tag gcr.io/your-project/vllm-deployment

# Deploy to Cloud Run
gcloud run deploy vllm-service \
  --image gcr.io/your-project/vllm-deployment \
  --platform managed \
  --region us-central1 \
  --memory 8Gi \
  --cpu 4 \
  --min-instances 0 \
  --max-instances 10 \
  --allow-unauthenticated
```

#### Step 4: Test Your Deployment

```bash  theme={null}
# Get the service URL
SERVICE_URL=$(gcloud run services describe vllm-service --region=us-central1 --format="value(status.url)")

# Test the API
curl -X POST "$SERVICE_URL/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model",
    "messages": [
      {"role": "user", "content": "What is the capital of France?"}
    ]
  }'
```

> You can also deploy your model on AWS, Azure, or other cloud platforms using vLLM or SGLang.

## Container Deployment

### Docker Compose

Create a `docker-compose.yml` for easy local deployment:

```yaml  theme={null}
version: "3.8"
services:
  model-api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - MODEL_NAME=your-model
      - MODEL_PATH=/app/model
    volumes:
      - ./model:/app/model
    deploy:
      resources:
        limits:
          memory: 8G
        reservations:
          memory: 4G

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - model-api
```

### Kubernetes Deployment

Deploy your model on Kubernetes for scalable production use:

```yaml  theme={null}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: model-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: model-api
  template:
    metadata:
      labels:
        app: model-api
    spec:
      containers:
        - name: model-api
          image: your-registry/model-api:latest
          ports:
            - containerPort: 8000
          resources:
            requests:
              memory: "4Gi"
              cpu: "2"
            limits:
              memory: "8Gi"
              cpu: "4"
          env:
            - name: MODEL_NAME
              value: "your-model"
---
apiVersion: v1
kind: Service
metadata:
  name: model-service
spec:
  selector:
    app: model-api
  ports:
    - port: 80
      targetPort: 8000
  type: LoadBalancer
```

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="Model Loading Errors">
    **Symptoms**: Model fails to load or returns errors

    **Solutions**:

    * Check model file integrity
    * Verify model format compatibility
    * Ensure sufficient memory allocation
    * Check file permissions
  </Accordion>

  <Accordion title="Performance Issues">
    **Symptoms**: Slow inference, high latency, timeouts **Solutions**: - Optimize
    model quantization - Increase compute resources - Implement caching - Use
    batch processing
  </Accordion>

  <Accordion title="Memory Issues">
    **Symptoms**: Out of memory errors, crashes **Solutions**: - Use quantized
    models - Increase memory allocation - Implement model sharding - Use smaller
    batch sizes
  </Accordion>

  <Accordion title="Network Issues">
    **Symptoms**: Connection timeouts, API failures

    **Solutions**:

    * Check network connectivity
    * Verify firewall settings
    * Implement retry logic
    * Use load balancing
  </Accordion>
</AccordionGroup>

## Next Steps

After deploying your model:

1. **Monitor Performance**: Track metrics and user feedback
2. **Scale as Needed**: Adjust resources based on usage patterns
3. **Iterate and Improve**: Use production data to improve your model
4. **Maintain Security**: Keep your deployment secure and updated

Your model is now ready for production use! Monitor its performance and gather feedback to continue improving your AI system.


# Developer's Guide
Source: https://facetai.mintlify.app/developer/index



This page is under construction, stay tuned!

We are migrating content from `README.md` in each directory to here!


# Inference and Export Guide
Source: https://facetai.mintlify.app/evaluation/inference_export

Complete guide to testing your models and exporting them for deployment

Use this guide to run quick checks and batch evaluations, compare models side‑by‑side, and export the final model for deployment.

## Run inference and evaluation

<Steps>
  <Step title="Select model(s)">
    Choose a trained or base model. Select two models to enable side‑by‑side comparisons.
  </Step>

  <Step title="Choose a mode">
    On the next screen, pick either Batch Inference (quick, lightweight checks) or Evaluation (full metrics on labeled data).
  </Step>

  <Step title="Load data">
    For Batch Inference: load a dataset and optionally limit the number of samples. For Evaluation: use a labeled eval split from preprocessing.
  </Step>

  <Step title="Run and monitor">
    Start the job and track progress. Large datasets take longer.
  </Step>

  <Step title="Review results">
    Inspect predictions vs. references (when available), compare models, and review summary metrics.
  </Step>
</Steps>

### Running batch inference

1. Load a dataset.
2. Select how many samples to run.
3. Review predictions vs. references (if available) for quick “vibe checks.”

<Tip>
  Batch inference is ideal for sanity checks before committing to a full evaluation.
</Tip>

### Evaluation

**Available Task Types**:

* `conversation` → BERTScore, ROUGE
* `qa` → Exact match, BERTScore
* `summarization` → ROUGE, BERTScore
* `translation` → BLEU, METEOR
* `classification` → Accuracy, Precision, Recall, F1
* `general` → BERTScore, ROUGE

<Tips>
  <Tip title="Use your eval split">
    You should already have an evaluation split from preprocessing.
  </Tip>

  <Tip title="Spot-check samples">
    Evaluations include example predictions vs. references for quick inspection.
  </Tip>

  <Tip title="Control sample size">
    You can limit the number of samples for faster runs.
  </Tip>
</Tips>

#### Using Specific Metrics

For more control, specify exact metrics to compute:

**Available Metrics**:

* `bertscore`: Semantic similarity (⭐ **Recommended for LLMs**)
* `rouge`: Text overlap and summarization quality
* `exact_match`: Perfect string matching
* `accuracy`: Token-level accuracy
* `precision`, `recall`, `f1`: Classification metrics
* `bleu`, `meteor`: Translation metrics

## Model export

Export your fine-tuned models in various formats for different deployment scenarios.

### Export Formats

<Tabs>
  <Tab title="Adapter Format">
    **Best for**: LoRA/QLoRA models, experimentation, combining adapters

    **Characteristics**:

    * Small file size (few MB)
    * Requires base model to run
    * Easy to merge with other adapters
    * Good for A/B testing different fine-tunings

    **Configuration**:

    ```json  theme={null}
    {
      "export_id": "exp_123",
      "job_id": "job_456",
      "type": "adapter",
      "destination": ["gcs", "hf_hub"],
      "hf_repo_id": "username/my-adapter"
    }
    ```
  </Tab>

  <Tab title="Merged Format">
    **Best for**: Standalone deployment, vLLM inference, production use

    **Characteristics**:

    * Self-contained model
    * Larger file size (several GB)
    * Ready for immediate deployment
    * Compatible with most inference engines
  </Tab>

  <Tab title="GGUF Format">
    **Best for**: CPU inference, local deployment, resource-constrained environments

    **Characteristics**:

    * Quantized for efficiency
    * CPU-optimized
    * Compatible with llama.cpp, ollama
    * Good for edge deployment
  </Tab>
</Tabs>

### Export Destinations

<CardGroup cols={2}>
  <Card title="Google Cloud Storage" icon="cloud">
    **Best for**: Downloading models, GCP deployments

    * Download as zip files
    * Direct integration with GCP services
    * Good for private model storage
  </Card>

  <Card title="Hugging Face Hub" icon="database">
    **Best for**: Sharing models, public deployment

    * Publish to HF Hub for sharing
    * Easy integration with HF ecosystem
    * Good for open-source projects
  </Card>
</CardGroup>

### GGUF Quantization Options

Choose the right quantization level for your needs:

<Tabs>
  <Tab title="q8_0 (Recommended)">
    **Best for**: Most use cases, good balance of quality and efficiency

    * 8-bit quantization
    * Good quality retention
    * Reasonable file size
    * Fast inference
  </Tab>

  <Tab title="q4_k_m">
    **Best for**: Maximum compression, resource‑constrained environments

    * 4-bit quantization
    * Smaller file size
    * Some quality loss
    * Very fast inference
  </Tab>

  <Tab title="f16">
    **Best for**: Maximum quality, when file size isn't critical

    * 16-bit floating point
    * Best quality
    * Larger file size
    * Slower inference
  </Tab>
</Tabs>

## Inference providers

When running inference and evaluation on Facet AI, you can select from multiple providers optimized for different use cases.

* Use the HF provider for non‑Unsloth models.
* Use the Unsloth provider for models trained with Unsloth.
* If you plan to deploy with vLLM, choose the vLLM provider to keep behavior consistent across environments.

## Best practices

### Inference Testing

<Tips>
  <Tip title="Start Simple">
    Begin with basic text prompts to verify your model works correctly.
  </Tip>

  <Tip title="Test Edge Cases">
    Try prompts that might be challenging or outside your training data.
  </Tip>

  <Tip title="Compare with Base Model">
    Test the same prompts with the base model to see improvements.
  </Tip>

  <Tip title="Use Diverse Prompts">
    Test with various prompt styles and formats to ensure robustness.
  </Tip>
</Tips>

### Evaluation Strategy

<Tips>
  <Tip title="Choose Appropriate Metrics">
    Select metrics that align with your task objectives and success criteria.
  </Tip>

  <Tip title="Use Multiple Metrics">
    Combine different types of metrics for a comprehensive assessment.
  </Tip>

  <Tip title="Analyze Sample Results">
    Look at individual predictions to understand model behavior.
  </Tip>

  <Tip title="Test on Held-out Data">
    Use data the model hasn't seen during training for unbiased evaluation.
  </Tip>
</Tips>

### Export Strategy

<Tips>
  <Tip title="Choose the Right Format">
    Select export format based on your deployment needs and constraints.
  </Tip>

  <Tip title="Consider File Size">
    Balance model quality with file size requirements for your deployment.
  </Tip>

  <Tip title="Test After Export">
    Verify your exported model works correctly in your target environment.
  </Tip>

  <Tip title="Document Your Model">
    Include model cards and documentation when sharing on HF Hub.
  </Tip>
</Tips>

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="Inference Fails">
    * Model not found or invalid model format
    * Insufficient resources available

    <Tip>
      Retry later or deploy on your cloud if you need guaranteed capacity.
    </Tip>
  </Accordion>
</AccordionGroup>

## Next Steps

After testing and exporting your model:

1. **Deploy Your Model**: Set up your model for production use
2. **Monitor Performance**: Track model performance in production
3. **Collect Feedback**: Gather user feedback to improve your model
4. **Iterate**: Use insights to refine your model with additional training

Ready to deploy? Head to the [Deployment guide](/deployment/deployment) to learn how to set up your model for production use.


# Eval and Exports Workflow
Source: https://facetai.mintlify.app/evaluation/introduction

Test your fine-tuned models and run comprehensive evaluations to assess performance

Evaluate a trained model with quick, interactive inference or run a batch job against a dataset to get objective metrics. Review results, compare to a baseline, and export the best checkpoint for deployment.

<Steps>
  <Step title="Select a model">
    Pick a completed training job or a previously exported model.

    <Check>
      Have the model source path and base model ID handy.
    </Check>
  </Step>

  <Step title="Choose evaluation mode">
    Start with single‑prompt inference to sanity‑check behavior, then move to batch evaluation on a labeled dataset.
  </Step>

  <Step title="Pick metrics">
    Select task‑appropriate metrics (e.g., BERTScore/ROUGE for generation, EM/F1 for QA, accuracy/F1 for classification).
  </Step>

  <Step title="Run and monitor">
    Launch the job and watch progress; large datasets take longer.
  </Step>

  <Step title="Review and compare">
    Inspect metrics and samples, compare against a baseline, and note failure patterns to guide the next training round.
  </Step>

  <Step title="Export for serving">
    When satisfied, export the model in your preferred format for deployment.
  </Step>
</Steps>

Next: see the [Inference & Export guide](/evaluation/inference_export) for detailed setup and options.


# Fine-Tuning Workflow
Source: https://facetai.mintlify.app/fine-tuning/introduction

Learn how to fine-tune Gemma models for your specific tasks using Facet's training service

Fine‑tune a Gemma model on your domain data with a simple, repeatable flow. You’ll pick a base model, choose a training method (SFT, DPO/ORPO, or GRPO), and run efficiently with Full, LoRA, or QLoRA depending on resources. Vision variants support text+image.

<Steps>
  <Step title="Prepare your dataset">
    Process data into conversation or preference format using the [dataset preprocessing guide](/dataset/introduction.mdx).

    <Check>
      Verify a small sample looks correct before training.
    </Check>
  </Step>

  <Step title="Select base model and method">
    Pick a Gemma size that fits your budget, then choose SFT (supervised), DPO/ORPO (preference), or GRPO (reasoning with rewards).
  </Step>

  <Step title="Enable PEFT and quantization if needed">
    Start with QLoRA for strong results on modest hardware; use Full finetune only when you need maximal capacity.
  </Step>

  <Step title="Launch and monitor">
    Start the job and watch training/validation signals to catch issues early.
  </Step>

  <Step title="Evaluate and iterate">
    Test the model, compare to the baseline, and iterate on data or settings.
  </Step>
</Steps>

Next: open the [Training guide](/fine-tuning/training) for step‑by‑step configuration details.


# Fine-tuning Guide
Source: https://facetai.mintlify.app/fine-tuning/training

Complete guide to configuring and launching training jobs in Facet

This comprehensive guide walks you through every aspect of training configuration, from selecting the right model to monitoring your training progress.

## Selecting Your Base Model

### Model Size Considerations

<Tabs>
  <Tab title="Small Models (270M-1B)">
    **Best for**: Simple tasks, quick prototyping, resource-constrained environments

    * **Gemma 3 270M**: Fastest, good for basic text generation
    * **Gemma 3 1B**: Balanced performance, good for most tasks

    <Tip>
      Start with 1B for most applications. It provides good performance while being resource-efficient.
      These models do not support vision fine-tuning!
    </Tip>
  </Tab>

  <Tab title="Medium Models (4B-12B)">
    **Best for**: Complex reasoning, high-quality responses, production use -
    **Gemma 3 4B**: High-quality responses, good for most production tasks -
    **Gemma 3 12B**: Advanced reasoning, complex problem-solving

    <Note>
      These models require more compute resources but offer significantly better
      performance.
    </Note>
  </Tab>

  <Tab title="Large Models (27B)">
    **Best for**: State-of-the-art performance, research, complex domains

    * **Gemma 3 27B**: Maximum performance, best for complex tasks

    <Warning>
      Large models require significant compute resources and longer training times.
    </Warning>
  </Tab>
</Tabs>

## Choosing Your Training Method

### Supervised Fine-Tuning (SFT)

**When to use**: General conversation, instruction following, domain adaptation

**Data format**: Language modeling

<AccordionGroup>
  <Accordion title="Best Practices">
    * Use high-quality conversation data
    * Include diverse examples
    * Ensure consistent formatting
    * Balance different types of interactions
  </Accordion>

  <Accordion title="Example Use Cases">
    * Customer service chatbots
    * Code assistants
    * Educational tutors
    * Domain-specific Q\&A systems
  </Accordion>
</AccordionGroup>

### Direct Preference Optimization (DPO)

**When to use**: Aligning models with human preferences, safety, helpfulness

**Data format**: Preference tuning (chosen vs rejected responses)

<AccordionGroup>
  <Accordion title="Data Requirements">
    * Paired examples (chosen vs rejected)
    * Clear preference signals
    * Diverse preference types
    * High-quality annotations
  </Accordion>

  <Accordion title="Example Use Cases">
    * Safety alignment
    * Helpfulness optimization
    * Style preference learning
    * Response quality improvement
  </Accordion>
</AccordionGroup>

### Odds Ratio Preference Optimization (ORPO)

**When to use**: Alternative to DPO, preference learning

**Data format**: Same as DPO (chosen vs rejected responses)

<Note>Unlike DPO, you do not need to perform SFT prior to ORPO training.</Note>

### Group-Related Policy Optimization (GRPO)

**When to use**: Reasoning tasks, math problems, structured thinking

**Data format**: Prompt-only (no assistant responses)

<AccordionGroup>
  <Accordion title="Reward Functions">
    * **Built-in**: Expression accuracy, numerical accuracy, format checking
    * **Reference-based**: String comparison, text similarity
    * **Model-based**: LLM scoring, classification, relative ranking
  </Accordion>

  <Accordion title="Example Use Cases">
    * Math problem solving
    * Logical reasoning
    * Code generation
    * Scientific problem solving
  </Accordion>
</AccordionGroup>

## PEFT Configuration

### Full Fine-tuning

**When to use**: Large datasets, major domain changes, maximum performance

**Pros**:

* Updates all parameters
* Maximum learning capacity
* Best for major domain shifts

**Cons**:

* Requires more memory
* Longer training time
* Higher compute costs

### LoRA (Low-Rank Adaptation)

**When to use**: Most fine-tuning tasks, good balance of performance and efficiency

**Pros**:

* Memory efficient
* Faster training
* Good performance
* Easy to merge

**Cons**:

* Slightly lower capacity than full fine-tuning
* May need higher rank for complex tasks

## Quantization Configuration

### QLoRA (Quantized LoRA)

**When to use**: Resource-constrained environments, most use cases

**Pros**:

* Most memory efficient
* Good performance
* Fast training
* Recommended default

**Cons**:

* Slight quantization overhead
* May need fine-tuning for optimal results

<Tip>
  Start with QLoRA for most tasks. It provides excellent results while using
  minimal resources.
</Tip>

Note that we currently only support 4 bit quantization for QLoRA. We will be moving away from bitsandbytes in the future to more robust methods, stay tuned.

## Hyperparameter Configuration

### Essential Parameters

<Tabs>
  <Tab title="Learning Rate">
    **Purpose**: Controls how much the model updates during training

    **Recommended values**:

    * Full fine-tuning: 0.00005
    * LoRA: 0.0001
    * QLoRA: 0.0002

    <Note>
      Lower learning rates are more stable but may require more epochs.
    </Note>
  </Tab>

  <Tab title="Batch Size">
    **Purpose**: Number of examples processed together **Recommended values**: -
    Small models: 4-8 - Medium models: 2-4 - Large models: 1-2

    <Warning>
      Larger batch sizes require more memory but may improve stability.
    </Warning>
  </Tab>

  <Tab title="Epochs">
    **Purpose**: Number of complete passes through the dataset

    **Recommended values**:

    * 1-3 epochs for most tasks

    <Tip>
      Monitor validation loss to avoid overfitting. Stop early if validation loss starts increasing.
    </Tip>
  </Tab>
</Tabs>

### Advanced Parameters

<AccordionGroup>
  <Accordion title="Gradient Accumulation">
    **Purpose**: Simulate larger batch sizes without using more memory

    **Formula**: Effective batch size = batch\_size × gradient\_accumulation\_steps

    **Example**: batch\_size=2, gradient\_accumulation\_steps=4 → effective batch\_size=8
  </Accordion>

  <Accordion title="Learning Rate Scheduler">
    **Purpose**: Adjusts learning rate during training **Options**: - `linear`:
    Linear decay from initial to 0 - `cosine`: Cosine annealing - `constant`:
    Fixed learning rate **Recommendation**: Use `linear` for most cases
  </Accordion>

  <Accordion title="Sequence Length">
    **Purpose**: Maximum length of input sequences

    **Considerations**:

    * Longer sequences use more memory
    * Should match your data's typical length
    * Common values: 1024, 2048, 4096

    **Recommendation**: Start with 2048, adjust based on your data
  </Accordion>
</AccordionGroup>

## Evaluation Configuration

Note that this evaluation is different from the inference/evaluation service used post-training. This calculates token-level metrics and raw eval loss.
For most use cases, you can disable this to speed up training and use the inference service for evaluation after training.

### Evaluation Strategies

* **`no`**: No evaluation (fastest training)
* **`steps`**: Evaluate every N steps
* **`epoch`**: Evaluate at the end of each epoch

<Tip>
  Use `epoch` evaluation for most cases. It provides regular feedback without
  slowing training significantly.
</Tip>

### Evaluation Metrics

The system automatically computes:

* **Accuracy**: Token-level accuracy
* **Perplexity**: Model's confidence in predictions

<Note>
  For task-specific metrics, use the inference service's evaluation endpoint
  after training.
</Note>

## Monitoring Training Progress

### Weights & Biases Integration

Track your training with W\&B for detailed monitoring by providing your API key.

## Trackio

We are working on this :)

## Export Configuration

<Tabs>
  <Tab title="Adapter Format">
    **Best for**: LoRA/QLoRA models, easy to merge later

    * Smaller file size
    * Requires base model to run
    * Easy to combine with other adapters
  </Tab>

  <Tab title="Merged Format">
    **Best for**: Standalone deployment, vLLM inference

    * Self-contained model
    * Larger file size
    * Ready for deployment
  </Tab>

  <Tab title="GGUF Format">
    **Best for**: CPU inference, llama.cpp, ollama

    * Quantized for efficiency
    * CPU-optimized
    * Good for local deployment
  </Tab>
</Tabs>

Learn more about export options on the [Inference, Evaluation, and Export](/evaluation/inference_export.mdx) page.

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="Out of Memory (OOM)">
    **Solutions**:

    * Reduce batch size
    * Increase gradient accumulation steps
    * Use QLoRA instead of LoRA
    * Reduce sequence length
    * Use a smaller model
  </Accordion>

  <Accordion title="Training Loss Not Decreasing">
    **Possible causes**: - Learning rate too high or too low - Poor data quality -
    Incorrect data format - Model too small for task **Solutions**: - Adjust
    learning rate - Check data quality - Verify data format - Try larger model
  </Accordion>

  <Accordion title="Overfitting">
    **Signs**:

    * Training loss much lower than validation loss
    * Validation loss increasing

    **Solutions**:

    * Reduce epochs
    * Increase dropout
    * Use more diverse data
    * Early stopping
  </Accordion>
</AccordionGroup>

## What's Next?

After your training completes:

1. **Evaluate Performance**: Use the evaluation tools to assess your model
2. **Export Your Model**: Download in your preferred format
3. **Deploy**: Set up your model for production use
4. **Iterate**: Use feedback to improve with additional training

Ready to evaluate your model? Head to the [Evaluation guide](/evaluation/introduction) to learn how to test your fine-tuned model.


# Facet AI
Source: https://facetai.mintlify.app/index

Democratizing LLM fine-tuning for everyone

## What is Facet AI?

Facet AI is a **no-code** platform that makes fine-tuning Gemma models accessible to everyone. Whether you're a developer or business user, you can create custom language models tailored to your specific needs with our streamlined platform and user-friendly interface.

## Key Features

Fine-tuned small language models (SLMs) are often more **cost-effective and performant** for specific use cases compared to generic LLMs. Learn more with [this article from Unsloth](https://docs.unsloth.ai/get-started/beginner-start-here/faq-+-is-fine-tuning-right-for-me). Facet AI simplifies this process with:

<CardGroup cols={2}>
  <Card title="Easy Dataset Preparation" icon="database">
    Upload your data or connect to Hugging Face Hub. We handle formatting for language modeling, preference tuning, and multimodal tasks.
  </Card>

  <Card title="Multiple Model Sizes" icon="computer">
    Fine-tune Gemma 3 models from 270M to 27B parameters, including Gemma 3n variants, using SFT, DPO, and GRPO.
  </Card>

  <Card title="Built-in Evaluation" icon="chart-line">
    Test your models with comprehensive inference and evaluation suites to measure performance before deployment.
  </Card>

  <Card title="Flexible Export" icon="download">
    Export models in multiple formats (adapter, merged, GGUF) with various quantizations for deployment anywhere.
  </Card>
</CardGroup>

## Quick Demo!

<iframe className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/JGnzoLSZReI" title="YouTube video player" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

<Info>
  Interested in more detailed walkthroughs? Check out our [video tutorials](/tutorials) covering common use cases and advanced techniques!
</Info>

## Getting Started

Choose your path based on your needs:

<CardGroup cols={3}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Get up and running in minutes using our managed platform. Perfect for trying out Facet AI.
  </Card>

  <Card title="Self-Deploy" icon="server" href="/deployment">
    Deploy Facet AI on your own cloud infrastructure for full control and customization.
  </Card>

  <Card title="Developer Guide" icon="code" href="/developer">
    Contribute to the open-source project or customize for your organization.
  </Card>
</CardGroup>

<Note>
  For production and enterprise use, deploy Facet AI to your own cloud for full control, security, and autoscaling. Our platform provides 100% Infrastructure-as-Code (IaC) for easy, automated setup. We have limited compute capacity on the managed platform to ensure fair usage for all users.
</Note>

## What We Support

<AccordionGroup>
  <Accordion title="Dataset Management">
    * Custom data uploads and Hugging Face Hub integration
    * Automatic dataset augmentation and preparation
    * Support for language modeling, preference tuning, and multimodal tasks
  </Accordion>

  <Accordion title="Model Training">
    * Gemma 3 family: 270M, 1B, 4B, 12B, 27B parameters
    * Gemma 3n variants: E2B and E4B
    * Training methods: SFT, DPO, and GRPO
  </Accordion>

  <Accordion title="Evaluation & Deployment">
    * Built-in inference and evaluation tools
    * Multiple export formats and quantizations
    * Easy deployment to Google Cloud Run and other providers
  </Accordion>
</AccordionGroup>

## Limitations

<Warning>
  **What Facet AI doesn't do:**

  * Web scraping for data collection
  * Hosting deployed models (you deploy them yourself)
  * Custom model architectures beyond Gemma variants
</Warning>

## Feature Requests

If you want us to expand on any documentation or any specific video tutorials, please open an issue on our GitHub repository! This project is maintained by two undergraduate students who need to balance academic and internship too, so please be patient with response times.

<Callout title="Need help?" type="info">
  Check out our [quickstart guide](/quickstart) to get started in minutes, or explore our [comprehensive tutorials](/tutorials) for detailed workflows.
</Callout>


# Quickstart
Source: https://facetai.mintlify.app/quickstart

Get started with Facet AI in minutes - fine-tune your first Gemma model

## Welcome to Facet AI

This quickstart guide will walk you through creating your first fine-tuned model using Facet AI. You'll go from data upload to model deployment in just a few steps.

<Note>
  **Prerequisites:** You'll need a Facet AI account. If you don't have one,
  [sign up here](https://gemma-facet.vercel.app) first.
</Note>

## Step 1: Create Your Account and Access the Platform

<Steps>
  <Step title="Sign up for Facet AI">
    1. Visit [Facet AI](https://gemma-facet.vercel.app)
    2. Click "Get Started" and create your account
    3. Verify your email address if required

    <Check>
      You should see the Facet AI dashboard after successful signup.
    </Check>
  </Step>

  <Step title="Navigate to the Dashboard">
    Once logged in, you'll see the main dashboard with sections for:

    * **Datasets**: Manage your training data
    * **Training**: Create and monitor fine-tuning jobs
    * **Models**: View your trained models
    * **Exports**: Download models in various formats

    <Tip>
      Bookmark the dashboard URL for easy access to your projects.
    </Tip>
  </Step>
</Steps>

## Step 2: Prepare Your Dataset

<Steps>
  <Step title="Upload Your Data">
    You have two options for getting your training data:

    <Tab title="Connect Hugging Face">
      1. Go to **Datasets** → **Create Dataset**
      2. Choose "Import from Hugging Face"
      3. Enter the dataset name (e.g., `huggingface/datasets`)
      4. Select the specific split you want to use

      <Tip>
        Popular datasets for fine-tuning: `wikitext`, `openwebtext`, `alpaca`
      </Tip>
    </Tab>

    <Tabs>
      <Tab title="Upload Custom Data">
        1. Go to **Datasets** → **Create Dataset**
        2. Choose "Upload from file"
        3. Upload your data file (CSV, JSON, or TXT)
        4. Give your dataset a descriptive name

        <Warning>
          Supported formats: CSV, JSON, TXT. Maximum file size: 100MB per upload.
        </Warning>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure Dataset Processing">
    1. After upload, configure your dataset:
       * **Task Type**: Choose from Language Modeling, Preference Tuning, or Multimodal
       * **Format**: Convert your dataset into conversational format for training
       * **Augmentation**: Setup data augmentation if desired
    2. Click "Process Dataset"

    <Check>
      Processing typically takes 1-5 minutes depending on dataset size.
    </Check>
  </Step>
</Steps>

## Step 3: Start Your First Training Job

<Steps>
  <Step title="Create Training Configuration">
    1. Go to **Training** → **New Job**
    2. Select your processed dataset from the dropdown
    3. Choose your model:
       * **Gemma 3 270M**: Fastest, good for experimentation
       * **Gemma 3 1B**: Balanced performance and speed
       * **Gemma 3 4B**: Better quality, longer training time
       * **Gemma 3 12B**: High quality, requires more resources

    <Info>
      For your first model, we recommend starting with Gemma 3 270M/1B to get quick results.
    </Info>
  </Step>

  <Step title="Configure Training Parameters">
    Set your training parameters (or use defaults):

    * **Learning Rate**: Start with default (0.0001)
    * **Batch Size**: Use default (4) for most cases
    * **Epochs**: Generally 1-3 epochs suffice, for testing limit to 100-500 training steps
    * **Training Method**: Select between SFT, DPO, or GRPO based on your task

    <Tip>
      You can adjust these parameters later as you become more experienced with fine-tuning.
    </Tip>
  </Step>

  <Step title="Launch Training">
    1. Review your configuration
    2. Give your training job a descriptive name
    3. Click "Start Training"

    <Check>
      Training will begin immediately. You can monitor progress in the Training section.
    </Check>
  </Step>
</Steps>

## Step 4: Monitor and Evaluate Your Model

<Steps>
  <Step title="Track Training Progress">
    1. Go to **Training** to see your active jobs
    2. Click on your training job to view detailed progress
    3. Monitor metrics like loss, learning rate, and training time

    <Note>
      Training time varies: 270M models train in \~30 minutes, while 12B models can take several hours.
    </Note>
  </Step>

  <Step title="Test Your Model">
    Once training completes:

    1. Go to **Models** section
    2. Find your newly trained model
    3. Click "Test Model" to run inference
    4. Try different prompts to evaluate performance

    <Tip>
      Test with various prompts to ensure your model performs well across different scenarios.
    </Tip>
  </Step>
</Steps>

## Step 5: Export and Deploy Your Model

<Steps>
  <Step title="Export Your Model">
    1. Go to **Exports** → **Create Export**
    2. Select your trained model
    3. Choose export format:
       * **GGUF**: For local deployment with llama.cpp
       * **Adapter**: For Hugging Face transformers
       * **Merged**: Complete model ready for deployment
    4. Select quantization level (4-bit, 8-bit, or 16-bit)
    5. Click "Create Export"

    <Check>
      Export typically takes 5-15 minutes depending on model size and format.
    </Check>
  </Step>

  <Step title="Download Your Model">
    1. Once export completes, click "Download"
    2. Save the model file to your local machine
    3. Your model is now ready for deployment!

    <Warning>
      Keep your model files secure and don't share them publicly unless intended.
    </Warning>
  </Step>
</Steps>

## Next Steps

Congratulations! You've successfully fine-tuned your first Gemma model. Here's what to explore next:

<CardGroup cols={2}>
  <Card title="Advanced Training" icon="cogs" href="/fine-tuning/training">
    Learn about DPO, GRPO, and advanced training techniques for better model performance.
  </Card>

  <Card title="Model Deployment" icon="rocket" href="/deployment/deployment">
    Deploy your models to production using Google Cloud Run or other platforms.
  </Card>

  <Card title="Evaluation Techniques" icon="chart-line" href="/evaluation/inference_export">
    Learn comprehensive evaluation methods to assess your model's quality.
  </Card>

  <Card title="Dataset Best Practices" icon="database" href="/dataset/datasets">
    Master dataset preparation for optimal fine-tuning results.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Training fails to start">
    * Check your dataset is properly processed
    * Ensure you have sufficient credits/quota
    * Verify your training parameters are valid
  </Accordion>

  <Accordion title="Poor model performance">
    * Try a larger model size (1B → 4B → 12B) - Increase training steps - Check
      your dataset quality and size - Consider data augmentation
  </Accordion>

  <Accordion title="Export issues">
    * Ensure training completed successfully
    * Try a different export format
    * Check your available storage quota
  </Accordion>
</AccordionGroup>

<Note>
  **Need more help?** Check out our [comprehensive tutorials](/tutorials) or
  contact support at [facet.gemma@gmail.com](mailto:facet.gemma@gmail.com).
</Note>


# Video Tutorials
Source: https://facetai.mintlify.app/tutorials

End-to-end walkthrough for real-world use cases

New to Facet AI? This is the best place to start! Our videos walk you through common real-world examples sourced from cookbooks, tutorials, and industry use cases.

<Note>
  We might not train the models with full dataset or very long epochs in these
  videos since the purpose is to demonstrate platform usage. If you wish to
  share a use case, feel free to post an issue [on our
  GitHub!](https://github.com/gemma-facet/docs).
</Note>

## Language Modeling with SFT

Videos in this section cover supervised fine-tuning (SFT), the most common method for adapting large language models to specific tasks using labeled datasets.

### Improving Gemma 270M by 50% at emotion classification

This example uses [emotions dataset from Hugging Face Hub](https://huggingface.co/datasets/boltuix/emotions-dataset) to fine-tune Gemma 270M for emotion classification.
In just 20 minutes of training, evaluation performance improved significantly and we are able to quickly try it out locally with Ollama.

<iframe className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/GkIl7LTiDjE?si=FvJlrnew0-D63a9G" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />

### Coming Soon

* Deploying models to cloud with vLLM
* LoRA on 4B models with vision datasets
* Fine tune 1B model on datasets with different language
* Using local datasets and dataset augmentation / synthesis
* Quickly benchmark Gemma models on common benchmark datasets from Hub

## Reinforcement Learning with GRPO

* Coming soon with reasoning examples...

## Preference Tuning with DPO / ORPO

* Coming soon...