Déployer AstaBrief 8B en local avec vLLM pour un RAG privé

AstaBrief 8B n'est pas un moteur de recherche documentaire : il transforme une question de recherche et des extraits scientifiques fournis en un rapport sourcé. C'est précisément ce qui rend son déploiement privé intéressant. Faites tourner le générateur derrière votre pare-feu, conservez l'analyse des documents et la recherche en local, puis transmettez au modèle uniquement les éléments de preuve classés, associés à des identifiants de source stables.

Ce dont AstaBrief 8B a réellement besoin

AstaBrief 8B est un modèle de génération de texte de 8 milliards de paramètres développé par Ai2, basé sur Qwen3-8B et distribué sous licence Apache 2.0. Sa fiche officielle définit comme entrée une question de recherche accompagnée d'extraits de publications scientifiques récupérés, et non une question que le modèle irait chercher lui-même. Elle avertit également qu'une modification du prompt ou du format d'interaction utilisés pour l'entraînement peut entraîner un comportement dégradé ou incohérent.

Pour ce guide, utilisez le checkpoint final allenai/AstaBrief_8B. L'exemple de la fiche du modèle mentionne allenai/AstaBrief_8B_SFT, qui correspond au modèle précédent, entraîné par supervised fine-tuning. Considérez cette différence de nom comme un point documentaire à vérifier par rapport au checkpoint téléchargé, plutôt que de supposer silencieusement que les deux modèles sont interchangeables.

Le dépôt public ScholarQA d'Ai2 permet de comprendre l'architecture de référence : recherche, reranking facultatif, regroupement au niveau des articles, extraction de citations et génération du rapport sont des composants distincts. Une implémentation privée devrait conserver cette séparation, même si elle remplace Semantic Scholar par un index interne.

Une architecture locale reproductible

Un pipeline privé devrait comporter six étapes clairement définies :

1. Ingestion : analysez les PDF, appliquez l'OCR aux pages numérisées et conservez l'identifiant du document, son titre, la page, la section et les offsets de caractères.
2. Découpage : divisez le texte en passages de taille modérée sans supprimer les limites de page ni les titres.
3. Recherche : combinez la recherche lexicale et les embeddings lorsque la terminologie, les identifiants ou les expressions exactes sont importants.
4. Reranking : évaluez les premiers candidats par rapport à la question complète et conservez un ensemble réduit d'éléments de preuve.
5. Assemblage : attribuez des identifiants de citation immuables et formatez les extraits selon la structure de références attendue par AstaBrief.
6. Génération : envoyez le prompt assemblé au endpoint vLLM local.

Le choix déterminant n'est pas celui d'une base vectorielle particulière. C'est le contrat de preuve : chaque passage transmis au modèle doit porter un identifiant stable que votre application peut relier à un document et à une page.

Conservez des identifiants de citation stables

Utilisez des identifiants comme DOC_014_P07_A plutôt que des positions dans un tableau. Les positions changent dès que les paramètres de recherche évoluent ; un identifiant combinant document, page et segment reste auditable.

Stockez la correspondance en dehors du prompt :

{
  "DOC_014_P07_A": {
    "document": "internal_protocol.pdf",
    "page": 7,
    "section": "Methods",
    "char_start": 18420,
    "char_end": 19210
  }
}

Dans le prompt, affichez le même identifiant à côté de l'extrait. Après la génération, rejetez ou signalez les citations qui ne figurent pas dans l'ensemble d'identifiants fourni. Cela ne prouve pas qu'un passage justifie chaque affirmation, mais empêche la forme la plus élémentaire de citation inventée.

Définissez la profondeur de recherche avant d'assembler le contexte

Ne versez pas dans le contexte chaque segment correspondant à la requête. Récupérez suffisamment de candidats pour maximiser le rappel, appliquez un reranking, puis ne conservez que les passages qui tiennent dans le budget du prompt et répondent directement à la question. Vous pouvez fusionner des segments adjacents provenant de la même page si cela permet de préserver un raisonnement complet, mais gardez des identifiants distincts si le rapport final doit assurer une traçabilité au niveau de la page.

Le dépôt Ai2 ScholarQA décrit une configuration de référence qui récupère 256 candidats, les rerank puis conserve 50 résultats au niveau des articles. Ces valeurs appartiennent à ce pipeline public et ne constituent pas une exigence universelle pour AstaBrief. Commencez avec des collections privées plus modestes, examinez les éléments manquants et ajustez la recherche ainsi que les limites de contexte en fonction de vos propres questions.

Servir AstaBrief 8B avec vLLM

La documentation officielle ne publie pas une exigence VRAM unique valable pour tous les types de données, toutes les longueurs de contexte et tous les niveaux de concurrence. Commencez avec le checkpoint non quantifié sur une machine capable de le charger, puis réduisez la concurrence ou la longueur du contexte avant d'évaluer une version quantifiée ; ne supposez pas que la quantification préservera le comportement des citations sans tester votre corpus.

Installez vLLM dans un environnement propre, compatible avec votre stack CUDA et PyTorch. Lancez ensuite le serveur compatible avec l'API OpenAI en utilisant le checkpoint final :

pip install -U vllm openai

vllm serve allenai/AstaBrief_8B \
  --host 127.0.0.1 \
  --port 8000 \
  --dtype auto \
  --max-model-len 16000

La valeur de --max-model-len constitue une limite opérationnelle, pas la promesse que chaque requête doit contenir 16 000 tokens ; la fiche du modèle indique une longueur maximale d'entraînement de 16 000 tokens, tandis que son exemple utilise max_tokens=4096 pour la génération.

Vérifiez le endpoint local

curl http://127.0.0.1:8000/v1/models

Appelez ensuite le serveur avec le même style de prompt que celui utilisé dans les données de fine-tuning. L'exemple officiel utilise une température de 0.7, un top-p de 0.95, un maximum de 4 096 tokens générés et le token EOS du tokenizer comme condition d'arrêt.

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8000/v1",
    api_key="local-only",
)

response = client.chat.completions.create(
    model="allenai/AstaBrief_8B",
    temperature=0.7,
    top_p=0.95,
    max_tokens=4096,
    messages=[
        {"role": "user", "content": assembled_prompt},
    ],
)

print(response.choices[0].message.content)

Sur un serveur privé, liez le service à l'interface loopback ou à une interface interne, placez l'authentification et TLS au niveau de votre passerelle, puis bloquez les accès entrants publics. Un modèle local ne rend pas automatiquement privés les journaux, les fichiers PDF temporaires ou le traçage.

Construire la requête de recherche privée

Le squelette ci-dessous laisse volontairement ouverte l'implémentation de l'index. Les éléments essentiels sont la liste des preuves classées, les identifiants immuables et la limite claire du prompt.

from dataclasses import dataclass
from openai import OpenAI

@dataclass
class Evidence:
    ref_id: str
    text: str
    title: str
    page: int


def build_prompt(question: str, evidence: list[Evidence]) -> str:
    references = "\n\n".join(
        f"[{item.ref_id}] {item.title} (page {item.page})\n{item.text}"
        for item in evidence
    )
    return f"""Research question:
{question}

Retrieved references:
{references}

Write a cited research report answering the question. Use only the supplied
references for factual support. Attach the supplied reference IDs to claims.
If the references do not establish a point, say that the evidence is
insufficient instead of inventing a source.
"""


def answer(question: str, evidence: list[Evidence]) -> str:
    client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="local-only")
    prompt = build_prompt(question, evidence)
    result = client.chat.completions.create(
        model="allenai/AstaBrief_8B",
        temperature=0.7,
        top_p=0.95,
        max_tokens=4096,
        messages=[{"role": "user", "content": prompt}],
    )
    return result.choices[0].message.content

En production, utilisez le modèle de prompt officiel d'AstaBrief et insérez-y vos extraits récupérés en préservant leurs identifiants de référence. L'instruction abrégée ci-dessus illustre l'intégration avec vLLM ; elle ne remplace pas le format utilisé pour le fine-tuning.

Votre index privé peut s'appuyer sur BM25, la recherche dense ou une approche hybride. Préservez les métadonnées à chaque étape. Un passage dépourvu d'identifiant de document et de numéro de page ne suffit pas à produire un rapport de recherche défendable, même si le texte généré semble juste.

Ajoutez un contrôle des citations et de la confidentialité avant la mise en production

Les résultats publiés d'AstaBrief sur ScholarQA-CS2 donnent un point de comparaison, mais ne garantissent rien pour votre corpus. Sur le jeu de test de 100 questions de la fiche du modèle, AstaBrief 8B affiche une précision des citations de 90.5 et un rappel des citations de 78.2 ; la précision des réponses atteint 89.0. Le fait que le rappel des citations soit inférieur à leur précision constitue un avertissement concret : un rapport peut citer correctement les éléments fournis tout en omettant des preuves pertinentes.

Mettez en place un contrôle en quatre points :

1. Validité des références : chaque identifiant de citation généré existe dans la liste autorisée de la requête.
2. Résolution des métadonnées : chaque identifiant renvoie vers un document, une page et un segment de texte stocké.
3. Vérification des preuves : un relecteur ou un vérificateur distinct contrôle que le passage justifie réellement l'affirmation associée.
4. Rappel de la recherche : entretenez un petit jeu de questions annotées contenant les documents et pages attendus, puis mesurez les éléments manquants après chaque modification du découpage, des embeddings ou du reranking.

Conservez le serveur de modèles, l'index, le stockage objet, les journaux et la supervision dans la même zone de confiance, sauf si votre politique autorise explicitement un service externe. Désactivez la journalisation du corps des requêtes pour les documents sensibles, masquez autant que possible les requêtes dans les traces et définissez une durée de conservation pour les PDF importés et les rapports générés.

Ne réutilisez pas le chiffre de 51.1 secondes en mode Fast publié par Ai2 comme référence pour votre déploiement local. Ce nombre décrit le pipeline Asta complet de bout en bout, alors qu'un déploiement auto-hébergé modifie le GPU, le système de recherche, le batching, la longueur du prompt et le chemin réseau. Mesurez séparément la recherche, le reranking, le délai avant le premier token, le temps de génération et la durée totale de la requête.

Diagnostiquez le déploiement couche par couche

Ce diagnostic par couches évite de prendre un échec de recherche pour une défaillance du modèle, ou de tenter de corriger un mauvais format de prompt en ajoutant davantage de documents.

Choisissez AstaBrief 8B si vous recherchez un générateur de rapports local spécialisé et si vous êtes prêt à prendre en charge la qualité de la recherche, la correspondance des sources et la validation. vLLM s'occupe de servir le modèle ; il ne fournit ni recherche documentaire, ni traçabilité des citations, ni contrôle de la confidentialité.

Sources

• Fiche du modèle AstaBrief 8B
• Documentation du serveur vLLM compatible avec OpenAI
• Modèle de prompt AstaBrief
• Bibliothèque Ai2 ScholarQA
• Annonce d'Ai2 consacrée à AstaBrief