Hugging Face's logo

Spaces:
CheeksTheGeek
/
temp
Sleeping

App Files Community
temp / DEPLOYMENT.md
CheeksTheGeek's picture
CheeksTheGeek
Initial commit: LLM Code Deployment System
c5292d8 unverified
preview code
|
Raw History Blame Contribute Delete
8 kB

Deployment Guide for Students

This guide will help you deploy your LLM Code Deployment API to Hugging Face Spaces so instructors can send you tasks and grade your work.

Prerequisites

  1. ✅ GitHub account with a personal access token
  2. ✅ Hugging Face account (free)
  3. ✅ AIPipe token from https://aipipe.org/login
  4. ✅ IIT Madras email (@ds.study.iitm.ac.in) for free AIPipe access

Step-by-Step Deployment

Step 1: Get Your AIPipe Token

  1. Visit https://aipipe.org/login
  2. Sign in with your @ds.study.iitm.ac.in email
  3. Copy your API token (starts with pk_)
  4. Important: You get $2/month free. Don't exceed this limit!

Step 2: Create GitHub Personal Access Token

  1. Go to https://github.com/settings/tokens
  2. Click "Generate new token" → "Generate new token (classic)"
  3. Give it a name like "LLM Code Deployment"
  4. Select scopes: ✅ repo (all permissions)
  5. Click "Generate token"
  6. Copy the token immediately (you won't see it again)

Step 3: Create a Hugging Face Space

  1. Go to https://huggingface.co/new-space
  2. Choose a name (e.g., llm-code-deploy-yourname)
  3. Select Docker as the SDK
  4. Make it Public
  5. Click Create Space

Step 4: Configure Environment Variables

In your Space, go to Settings → Variables and secrets:

Add these environment variables (not secrets):

Variable Value
STUDENT_EMAIL Your email (e.g., yourname@ds.study.iitm.ac.in)
STUDENT_SECRET A secret phrase (e.g., mySecretKey123)
GITHUB_USERNAME Your GitHub username
LLM_PROVIDER aipipe
LLM_MODEL google/gemini-2.0-flash-lite-001

Add these as secrets (hidden values):

Secret Value
GITHUB_TOKEN Your GitHub personal access token
AIPIPE_TOKEN Your AIPipe token

Step 5: Deploy Your Code

Option A: Push from Local Repository

# Clone your repository
git clone https://github.com/YOUR_USERNAME/tds-p1.git
cd tds-p1

# Add Hugging Face Space as remote
git remote add space https://huggingface.co/spaces/YOUR_HF_USERNAME/YOUR_SPACE_NAME

# Push to Space
git push space main

Option B: Upload Files Directly

  1. In your Space, click Files → Add file
  2. Upload these files:
    • Dockerfile
    • requirements.txt
    • All .py files
    • templates/ folder
    • .gitignore

Step 6: Wait for Build

  1. Go to the Logs tab
  2. Wait for the build to complete (5-10 minutes)
  3. Look for: Application startup complete in the logs

Step 7: Test Your Deployment

Your API endpoint will be:

https://YOUR_HF_USERNAME-YOUR_SPACE_NAME.hf.space/api/build

Test it:

curl https://YOUR_HF_USERNAME-YOUR_SPACE_NAME.hf.space/health

Expected response:

{
  "status": "healthy",
  "active_tasks": 0,
  "timestamp": "2025-01-16T10:30:00.123456"
}

Step 8: Submit to Instructors

  1. Go to the instructor's Google Form
  2. Submit:
    • API Endpoint: https://YOUR_HF_USERNAME-YOUR_SPACE_NAME.hf.space/api/build
    • Secret: Same value you used in STUDENT_SECRET
    • Email: Same value you used in STUDENT_EMAIL

What Happens Next?

  1. Instructors send tasks → Your API receives a JSON request
  2. Code generation → LLM generates a web app based on the task
  3. GitHub deployment → New repo is created and pushed
  4. Pages deployment → GitHub Pages is enabled
  5. Notification → Your API notifies the evaluation endpoint
  6. Grading → Instructors run automated checks

Monitoring Your Deployment

View Logs

In your Space:

  • Logs tab shows real-time activity
  • Look for task requests, code generation, and deployment status

Check GitHub

Generated repos will appear at:

https://github.com/YOUR_GITHUB_USERNAME/

Each task creates a new repo like:

sum-of-sales-abc12
markdown-to-html-def34

Monitor AIPipe Usage

Visit https://aipipe.org/usage to see:

  • How much of your $2/month quota you've used
  • Number of API calls made
  • Estimated cost

Troubleshooting

Space won't build

Error: Build fails with dependency errors

Solution:

  1. Check Dockerfile is present and correct
  2. Verify requirements.txt has all dependencies
  3. Review Logs for specific error messages

Invalid secret error

Error: 401 Unauthorized: Invalid secret

Solution:

  1. Check STUDENT_SECRET matches what you submitted in the form
  2. Verify STUDENT_EMAIL is correct
  3. Test with the exact same values

GitHub authentication fails

Error: Failed to create repository

Solution:

  1. Verify GITHUB_TOKEN is set as a secret (not variable)
  2. Ensure token has repo permissions
  3. Check token hasn't expired (they last 1 year by default)

LLM API errors

Error: LLM generation failed: 401 Unauthorized

Solution:

  1. Verify AIPIPE_TOKEN is correct
  2. Check you haven't exceeded $2/month quota
  3. Try a different model: anthropic/claude-3-haiku

GitHub Pages not deploying

Error: Pages URL returns 404

Solution:

  1. Wait 60-120 seconds for Pages to activate
  2. Check repo is public (not private)
  3. Verify Pages is enabled in repo settings

Cost Optimization

Recommended Models (Cheapest to Most Expensive)

  1. google/gemini-2.0-flash-lite-001 ✅ Recommended

    • $0.00001/1K tokens (cheapest)
    • ~$0.02 per task
    • ~100 tasks per $2

  2. anthropic/claude-3-haiku

    • $0.00025/1K tokens
    • ~$0.50 per task
    • ~4 tasks per $2

  3. openai/gpt-4.1-nano

    • $0.0004/1K tokens
    • ~$0.80 per task
    • ~2.5 tasks per $2

Tips to Reduce Costs

  • ✅ Use Gemini Flash Lite (default)
  • ✅ Test locally before deploying
  • ✅ Monitor usage at https://aipipe.org/usage
  • ❌ Don't use GPT-4 or Claude Sonnet (expensive)
  • ❌ Don't test excessively (each test costs money)

Alternative: Run Locally (No Cost)

If you prefer not to use AIPipe, run the instructor evaluation locally:

# Set up with your own Anthropic/OpenAI key
echo "LLM_PROVIDER=anthropic" >> .env
echo "ANTHROPIC_API_KEY=sk-ant-your-key" >> .env

# Run student API locally
uv run python main.py student-api

# Use ngrok to expose it publicly
ngrok http 8000

Then submit the ngrok URL to instructors.

FAQ

Can I use a different LLM provider?

Yes! Change these environment variables:

For Anthropic Claude:

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-your-key
LLM_MODEL=claude-3-5-sonnet-20241022

For OpenAI:

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-key
LLM_MODEL=gpt-4-turbo-preview

How long does code generation take?

  • Gemini Flash Lite: 2-5 seconds
  • Claude Haiku: 3-7 seconds
  • GPT-4: 5-15 seconds

Plus:

  • GitHub deployment: 30-60 seconds
  • Pages activation: 30-120 seconds
  • Total: ~2-5 minutes per task

Can I see the generated code before deployment?

Yes! Check the logs:

# View logs in real-time
curl https://YOUR_SPACE.hf.space/api/status/TASK_ID

Or check the generated repo on GitHub after deployment.

What if I exceed the $2 limit?

  1. AIPipe will block your requests
  2. Use your own API key (see alternative providers above)
  3. Contact instructors for assistance

How many tasks will I receive?

Instructors may send:

  • Round 1: 1-3 tasks
  • Round 2: 1-3 update tasks per Round 1 task
  • Total: 2-9 tasks

With Gemini Flash Lite (~$0.02/task), you'll use ~$0.18 total. Well within the $2 limit!

Support

If you encounter issues:

  1. Check logs: Space → Logs tab
  2. Review this guide: Especially troubleshooting section
  3. Test locally: Run the API locally to debug
  4. Ask instructors: In the course forum or office hours

Next Steps

After deployment:

  1. ✅ Submit your endpoint to the Google Form
  2. ✅ Wait for tasks from instructors
  3. ✅ Monitor logs and GitHub for activity
  4. ✅ Check evaluation results after deadline

Good luck! 🚀