AstaBrief 8B: deployment locale con vLLM per RAG privato

AstaBrief 8B non è un retriever: prende una domanda di ricerca e alcuni estratti scientifici forniti dall’esterno e li trasforma in un report con citazioni. È proprio questa distinzione a rendere possibile un deployment privato. Esegui il generatore dietro il firewall, mantieni parsing e ricerca dei documenti in locale e invia al modello soltanto le evidenze ordinate, associate a identificativi stabili.

Di cosa ha davvero bisogno AstaBrief 8B

AstaBrief 8B è un modello di generazione testuale da 8 miliardi di parametri sviluppato da Ai2, basato su Qwen3-8B e distribuito con licenza Apache 2.0. La model card ufficiale descrive come input una domanda di ricerca accompagnata da estratti della letteratura scientifica recuperati in precedenza: non è il modello a cercare autonomamente le fonti. La documentazione avverte inoltre che modificare il prompt o il formato di interazione usato nel fine-tuning può causare comportamenti peggiori o incoerenti.

Per questa guida usa il checkpoint finale allenai/AstaBrief_8B. L’esempio riportato nella model card contiene allenai/AstaBrief_8B_SFT, cioè il predecessore sottoposto a supervised fine-tuning. Considera quindi la differenza tra i due nomi un dettaglio documentale da verificare rispetto al checkpoint che scarichi, senza dare per scontato che i due modelli siano intercambiabili.

Il repository pubblico ScholarQA di Ai2 è utile per capire l’architettura di riferimento: retrieval, reranking opzionale, aggregazione a livello di paper, estrazione delle citazioni e generazione del report sono componenti separate. Anche un’implementazione privata dovrebbe mantenere questa separazione, sostituendo eventualmente Semantic Scholar con un indice interno.

Un’architettura locale riproducibile

Una pipeline privata dovrebbe articolarsi in sei fasi esplicite:

1. Ingestione: analizza i PDF, esegui l’OCR delle pagine scansionate e conserva ID del documento, titolo, pagina, sezione e offset dei caratteri.
2. Suddivisione: separa il testo in passaggi di dimensioni moderate senza perdere i confini delle pagine o i titoli delle sezioni.
3. Retrieval: combina la ricerca lessicale con gli embedding quando contano terminologia, identificativi o frasi esatte.
4. Reranking: rivaluta i candidati della prima fase rispetto alla domanda completa e conserva un insieme ristretto di evidenze.
5. Assemblaggio: assegna ID immutabili alle citazioni e formatta gli estratti secondo la struttura di riferimenti attesa da AstaBrief.
6. Generazione: invia il prompt assemblato all’endpoint vLLM locale.

La scelta determinante non è uno specifico database vettoriale. È il contratto delle evidenze: ogni passaggio inviato al modello deve avere un ID stabile che l’applicazione possa ricondurre a un documento e a una pagina.

Mantieni stabili gli ID delle citazioni

Usa ID come DOC_014_P07_A invece delle posizioni nell’array. Gli indici cambiano quando modifichi i parametri del retrieval; un identificativo basato su documento, pagina e intervallo resta invece verificabile.

Conserva la corrispondenza al di fuori del prompt:

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

Nel prompt mostra lo stesso ID accanto all’estratto. Dopo la generazione, rifiuta o segnala le citazioni che non appartengono all’insieme di ID fornito. Questo non dimostra che un passaggio supporti ogni singola affermazione, ma elimina la forma più semplice di citazione inventata.

Stabilisci la profondità del retrieval prima di assemblare il contesto

Non riversare nel contesto tutti i chunk che corrispondono alla query. Recupera abbastanza risultati da privilegiare il recall, applica il reranking e inserisci soltanto i passaggi compatibili con il budget del prompt e direttamente utili alla domanda. Puoi unire chunk adiacenti della stessa pagina quando in questo modo preservi un ragionamento completo, ma mantieni ID distinti se il report finale deve garantire la tracciabilità a livello di pagina.

Il repository Ai2 ScholarQA descrive una configurazione di riferimento che recupera 256 candidati, li sottopone a reranking e conserva 50 risultati a livello di paper. Questi valori appartengono a quella pipeline pubblica, non sono requisiti universali di AstaBrief. Parti da collezioni private più piccole, analizza le evidenze mancate e calibra retrieval e limiti del contesto sulle tue domande.

Esegui AstaBrief 8B con vLLM

La documentazione ufficiale non indica un unico requisito di VRAM valido per ogni dtype, lunghezza del contesto e livello di concorrenza. Parti dal checkpoint non quantizzato su hardware in grado di caricarlo, poi riduci concorrenza o lunghezza del contesto prima di valutare una build quantizzata; non dare per scontato che la quantizzazione mantenga invariato il comportamento delle citazioni senza testarla sul tuo corpus.

Installa vLLM in un ambiente pulito e compatibile con lo stack CUDA e PyTorch in uso. Avvia quindi il server compatibile con le API OpenAI usando il checkpoint finale:

pip install -U vllm openai

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

Il valore di --max-model-len è un limite operativo superiore, non significa che ogni richiesta debba contenere 16.000 token. La model card indica un massimo di addestramento di 16.000 token, mentre l’esempio usa max_tokens=4096 per la generazione.

Verifica l’endpoint locale

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

Prova poi una richiesta usando lo stesso stile di prompt dei dati di fine-tuning. L’esempio ufficiale utilizza temperature 0.7, top-p 0.95, un massimo di 4.096 token generati e il token EOS del tokenizer come condizione di arresto.

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)

Su un server privato, fai il bind sull’interfaccia loopback o su una rete interna, gestisci autenticazione e TLS dal gateway e blocca gli accessi pubblici. Un modello locale non rende automaticamente privati i log, i PDF temporanei o i sistemi di tracing.

Costruisci la richiesta di retrieval privata

Lo scheletro seguente lascia volutamente aperta l’implementazione dell’indice. Gli elementi essenziali sono l’elenco ordinato delle evidenze, gli ID immutabili e il confine del 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

In produzione usa il template ufficiale del prompt AstaBrief e inserisci gli estratti recuperati mantenendo i relativi ID. L’istruzione abbreviata qui sopra mostra l’integrazione con vLLM, ma non sostituisce il formato usato nel fine-tuning.

Il tuo indice privato può usare BM25, retrieval denso o un approccio ibrido. Mantieni i metadati lungo tutte le fasi. Un passaggio privo di ID del documento e numero di pagina non basta per produrre un report di ricerca difendibile, anche quando la prosa generata sembra corretta.

Inserisci un controllo su citazioni e privacy prima della produzione

I risultati dichiarati da AstaBrief su ScholarQA sono un riferimento utile, non una garanzia per il tuo corpus. Sul test set della model card, composto da 100 domande, AstaBrief 8B riporta una precisione delle citazioni di 90.5 e un recall delle citazioni di 78.2; la precisione delle risposte è 89.0. Il fatto che il recall delle citazioni sia inferiore alla precisione è un avvertimento concreto: un report può citare correttamente il materiale fornito e allo stesso tempo omettere evidenze rilevanti.

Applica un controllo composto da quattro verifiche:

1. Validità dei riferimenti: ogni ID citato dal modello deve esistere nell’allow-list della richiesta.
2. Risoluzione dei metadati: ogni ID deve rimandare a un documento, a una pagina e a un intervallo di testo archiviato.
3. Supporto dell’evidenza: un revisore o un verificatore separato deve controllare che il passaggio supporti davvero l’affermazione a cui è associato.
4. Recall del retrieval: mantieni un piccolo set di domande annotate con i documenti e le pagine attesi, poi misura gli elementi mancanti dopo ogni modifica a chunking, embedding o reranking.

Mantieni server del modello, indice, object storage, log e sistemi di monitoraggio all’interno dello stesso perimetro di fiducia, salvo che la tua policy autorizzi esplicitamente un servizio esterno. Disabilita il logging del corpo delle richieste per i documenti sensibili, oscura le query nei trace quando possibile e definisci i tempi di conservazione per PDF caricati e report generati.

Non usare il dato di 51,1 secondi dichiarato da Ai2 per la modalità Fast come benchmark del tuo ambiente locale. Quel numero descrive l’intera pipeline Asta, mentre un deployment self-hosted cambia GPU, sistema di retrieval, batching, lunghezza del prompt e percorso di rete. Misura separatamente retrieval, reranking, tempo al primo token, durata della generazione e tempo complessivo della richiesta.

Fai troubleshooting per livello

Questa diagnosi a livelli evita di scambiare un problema di retrieval per un malfunzionamento del modello e impedisce di “risolvere” un formato di prompt errato aggiungendo altri documenti.

Scegli AstaBrief 8B se cerchi un generatore locale specializzato in report e sei disposto a gestire direttamente qualità del retrieval, mappatura delle fonti e validazione. vLLM risolve il model serving, ma non offre ricerca documentale, provenienza delle citazioni o controlli sulla privacy.

Fonti

• Model card di AstaBrief 8B
• Documentazione del server compatibile con OpenAI di vLLM
• Template del prompt AstaBrief
• Libreria Ai2 ScholarQA
• Annuncio di Ai2 su AstaBrief