README.md

metadata

title: Hilal Ai Telegram Bot
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
pinned: false

Hilal Ai — Bot Telegram hébergé sur Hugging Face Spaces (gratuit)

Ce Space fait tourner en continu un bot Telegram propulsé par un modèle Transformer décodeur (style GPT) entraîné from scratch au niveau caractère.

⚠️ Comprendre les limites du tier gratuit AVANT de déployer

Le tier CPU Basic de HF Spaces est gratuit mais se met en veille après ~48h sans "visite" sur la page web du Space. Un bot Telegram en polling n'a pas de visiteurs web naturellement, donc ce repo inclut :

• un petit serveur Flask (app.py) qui répond sur / et /ping
• des instructions ci-dessous pour qu'un service externe gratuit (UptimeRobot ou GitHub Actions) ping cette URL régulièrement et empêche la mise en veille

C'est une solution bricolée mais fonctionnelle. Elle n'est pas garantie à 100% par Hugging Face (ce n'est pas un usage "officiellement prévu" du tier gratuit) — si tu veux une garantie de disponibilité totale, il faudra upgrader le hardware du Space (~9$/mois) qui élimine la mise en veille.

Fichiers du repo

.
├── Dockerfile          # image Docker du Space (SDK: docker)
├── app.py              # serveur web de ping + lance bot.py dans un thread
├── bot.py              # logique du bot Telegram
├── model.py            # architecture MiniGPT + tokenizer char-level
├── requirements.txt
├── .gitattributes      # config Git LFS pour model.pt
├── model.pt            # TES poids entraînés (à uploader, voir ci-dessous)
└── vocab.json          # TON vocabulaire char-level (voir ci-dessous)

⚠️ vocab.json est OBLIGATOIRE pour des réponses cohérentes

Le tokenizer char-level a besoin du mapping exact caractère→indice utilisé pendant l'entraînement sur Colab. Sans lui, le modèle se chargera sans erreur mais générera des réponses incohérentes (les embeddings ne correspondront pas aux bons caractères).

Si tu as encore accès à ton notebook Colab ou ton corpus d'entraînement :

import json
chars = sorted(list(set(text)))  # `text` = ton corpus d'entraînement original
with open("vocab.json", "w", encoding="utf-8") as f:
    json.dump({"chars": chars}, f, ensure_ascii=False)

Étape 1 — Créer le Space sur Hugging Face

1. Va sur https://huggingface.co/new-space (tu es déjà connecté à ton compte)
2. Choisis un nom (ex: hilal-ai-bot)
3. SDK : sélectionne Docker (pas Gradio)
4. Visibilité : Public ou Private selon ta préférence
5. Clique sur "Create Space"

Étape 2 — Ajouter le token Telegram comme secret

Dans la page de ton Space : Settings → Repository secrets → New secret

• Nom : TELEGRAM_BOT_TOKEN
• Valeur : le token obtenu via @BotFather sur Telegram

Ne mets jamais ce token directement dans le code ou dans un fichier commité.

Étape 3 — Pousser le code sur le Space

Hugging Face Spaces fonctionne comme un repo Git classique.

# Installer git-lfs si pas déjà fait (pour model.pt)
git lfs install

# Cloner le repo vide de ton Space (remplace USERNAME et SPACE_NAME)
git clone https://huggingface.co/spaces/USERNAME/SPACE_NAME
cd SPACE_NAME

# Copier tous les fichiers de ce dossier dedans :
# Dockerfile, app.py, bot.py, model.py, requirements.txt, .gitattributes,
# model.pt, vocab.json

git lfs track "*.pt"
git add .gitattributes
git add .
git commit -m "Déploiement initial Hilal Ai"
git push

HF va automatiquement builder l'image Docker. Tu peux suivre les logs de build et d'exécution dans l'onglet Logs de ton Space.

Étape 4 — Vérifier que le bot tourne

1. Va sur l'URL de ton Space : https://huggingface.co/spaces/USERNAME/SPACE_NAME
2. L'app Flask doit répondre avec {"bot_started": true, ...} sur la page
3. Sur Telegram, cherche ton bot et envoie /start

Étape 5 — Empêcher la mise en veille (keep-alive externe)

L'URL publique de ton Space (format direct, sans iframe) est généralement :

https://USERNAME-SPACE_NAME.hf.space/ping

Option A — UptimeRobot (recommandé, zéro code)

1. Crée un compte gratuit sur https://uptimerobot.com
2. Ajoute un nouveau monitor de type "HTTP(s)"
3. URL : https://USERNAME-SPACE_NAME.hf.space/ping
4. Intervalle : 30 minutes (largement suffisant pour rester sous 48h)

Option B — GitHub Actions (si tu préfères tout garder versionné)

Crée .github/workflows/keep-alive.yml dans un repo GitHub que tu contrôles :

name: Keep Hilal Ai Space Alive
on:
  schedule:
    - cron: '0 */6 * * *'  # toutes les 6 heures
  workflow_dispatch:
jobs:
  ping:
    runs-on: ubuntu-latest
    steps:
      - name: Ping Space
        run: curl -f https://USERNAME-SPACE_NAME.hf.space/ping

Variables d'environnement disponibles (Secrets ou Variables du Space)

Variable	Défaut	Description
TELEGRAM_BOT_TOKEN	(obligatoire)	Token du bot Telegram
MODEL_PATH	model.pt	Chemin vers les poids
VOCAB_PATH	vocab.json	Chemin vers le vocabulaire char-level
DEVICE	cpu (auto)	"cpu" (les Spaces gratuits n'ont pas de GPU)
MAX_NEW_TOKENS	200	Nombre max de caractères générés par réponse
TEMPERATURE	0.7	Température de sampling
PORT	7860	Port du serveur Flask (imposé par HF Spaces)

Diagnostiquer un problème

• Le build Docker échoue → onglet "Logs" du Space, section "Build logs"
• Le bot ne répond pas sur Telegram mais le Space tourne → vérifie les "Container logs" pour une erreur de chargement du modèle ou de token manquant
• Page d'accueil affiche bot_started: false → le thread du bot a crashé au démarrage (vérifie model.pt/vocab.json présents et valides)