Como rodar o AstaBrief 8B localmente com vLLM para RAG privado

O AstaBrief 8B não faz buscas: ele transforma uma pergunta de pesquisa e trechos científicos fornecidos pelo sistema em um relatório com citações. Essa distinção é fundamental em uma implantação privada. Mantenha o gerador atrás do firewall, faça o parsing dos documentos e a busca localmente e envie ao modelo apenas as evidências ranqueadas, acompanhadas de IDs de fonte estáveis.

O que o AstaBrief 8B realmente precisa

O AstaBrief 8B é um modelo de geração de texto com 8 bilhões de parâmetros, criado pela Ai2, baseado no Qwen3-8B e distribuído sob a licença Apache 2.0. O model card oficial define como entrada uma pergunta de pesquisa e trechos recuperados da literatura científica — não uma pergunta que o próprio modelo pesquisa. O documento também alerta que alterar o prompt ou o formato de interação usados no fine-tuning pode resultar em um comportamento degradado ou inconsistente.

Use o checkpoint final allenai/AstaBrief_8B neste guia. O exemplo do model card contém allenai/AstaBrief_8B_SFT, que é o antecessor usado no supervised fine-tuning. Trate essa diferença de nomes como um detalhe de documentação que precisa ser conferido em relação ao checkpoint baixado, em vez de presumir silenciosamente que os dois modelos são intercambiáveis.

O repositório público Ai2 ScholarQA ajuda a entender o desenho de referência: recuperação, reranking opcional, agregação por artigo, extração de citações e geração do relatório são componentes separados. Uma implementação privada deve manter essa separação, mesmo que substitua o Semantic Scholar por um índice interno.

Uma arquitetura local reproduzível

Um pipeline privado deve ter seis etapas bem definidas:

1. Ingestão: faça o parsing dos PDFs, aplique OCR às páginas digitalizadas e preserve o ID do documento, título, página, seção e offsets de caracteres.
2. Divisão em trechos: separe o texto em passagens de tamanho moderado sem descartar os limites de página nem os títulos.
3. Recuperação: combine busca lexical com embeddings quando terminologia, identificadores ou frases exatas forem importantes.
4. Reranking: pontue os candidatos da primeira etapa em relação à pergunta completa e mantenha um conjunto pequeno de evidências.
5. Montagem: atribua IDs de citação imutáveis e formate os trechos de acordo com a estrutura de referências esperada pelo AstaBrief.
6. Geração: envie o prompt montado ao endpoint local do vLLM.

A decisão de arquitetura mais importante não é escolher um banco vetorial específico. É definir o contrato da evidência: toda passagem enviada ao modelo precisa carregar um ID estável que a aplicação consiga associar novamente a um documento e a uma página.

Não deixe os IDs de citação mudarem

Prefira IDs como DOC_014_P07_A a posições em arrays. As posições mudam quando os parâmetros de recuperação são alterados; um ID baseado em documento, página e trecho continua auditável.

Armazene o mapeamento fora do prompt:

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

No prompt, mostre o mesmo ID ao lado do trecho. Depois da geração, rejeite ou sinalize citações que não estejam no conjunto de IDs fornecido. Isso não prova que uma passagem sustenta todas as afirmações feitas, mas bloqueia a forma mais básica de fabricação de citações.

Defina a profundidade da busca antes de montar o contexto

Não despeje no contexto todos os trechos encontrados. Recupere uma quantidade ampla o suficiente para garantir recall, faça o reranking e então empacote apenas as passagens que caibam no orçamento do prompt e respondam diretamente à pergunta. Una trechos adjacentes da mesma página quando isso preservar um argumento completo, mas mantenha IDs separados se o relatório final precisar de rastreabilidade em nível de página.

O repositório Ai2 ScholarQA descreve uma configuração de referência que recupera 256 candidatos, faz o reranking e mantém 50 resultados em nível de artigo. Esses valores pertencem àquele pipeline público, não são uma exigência universal do AstaBrief. Comece com coleções privadas menores, analise as evidências que ficaram de fora e ajuste os limites de recuperação e contexto com base nas suas próprias perguntas.

Sirva o AstaBrief 8B com vLLM

Os materiais oficiais não publicam um requisito único de VRAM para todas as combinações de dtype, tamanho de contexto e nível de concorrência. Comece com o checkpoint sem quantização em um hardware capaz de carregá-lo e reduza a concorrência ou o tamanho do contexto antes de avaliar uma versão quantizada; não presuma que a quantização preservará o comportamento das citações sem testá-la no seu corpus.

Instale o vLLM em um ambiente limpo, compatível com sua pilha de CUDA e PyTorch. Em seguida, inicie o servidor compatível com a API da OpenAI usando o 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

O valor de --max-model-len é um teto operacional, não uma promessa de que toda requisição deve conter 16.000 tokens; o model card informa um máximo de treinamento de 16.000 tokens, enquanto o exemplo usa max_tokens=4096 para a geração.

Verifique o endpoint local

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

Depois, faça uma chamada usando o mesmo estilo de prompt adotado nos dados de fine-tuning. O exemplo oficial usa temperatura 0.7, top-p 0.95, no máximo 4.096 tokens gerados e o token EOS do tokenizer como condição de parada.

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)

Em um servidor privado, faça o bind no loopback ou em uma interface interna, coloque autenticação e TLS no gateway e bloqueie o acesso público. Um modelo local não torna automaticamente privados os logs, os arquivos PDF temporários ou os dados de tracing.

Monte a requisição de recuperação privada

O esqueleto a seguir deixa deliberadamente em aberto a implementação do índice. As partes realmente importantes são a lista de evidências ranqueadas, os IDs imutáveis e o limite do 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

Em produção, use o template oficial de prompt do AstaBrief e insira os trechos recuperados preservando os IDs de referência. A instrução reduzida acima ilustra a integração com o vLLM; ela não substitui o formato usado no fine-tuning.

Seu índice privado pode usar BM25, recuperação densa ou uma abordagem híbrida. Preserve os metadados em todas as etapas. Uma passagem sem o ID do documento e o número da página não é suficiente para um relatório de pesquisa defensável, mesmo que o texto gerado pareça correto.

Adicione uma barreira de citações e privacidade antes de colocar em produção

Os resultados divulgados do AstaBrief no ScholarQA-CS2 são um contexto útil, não uma garantia para o seu corpus. No conjunto de teste do model card, com 100 perguntas, o AstaBrief 8B informa precisão de citação de 90.5 e recall de citação de 78.2; a precisão das respostas é 89.0. O recall de citações ser menor que a precisão é um alerta prático: um relatório pode citar corretamente o material fornecido e ainda deixar de fora evidências relevantes.

Use uma barreira com quatro verificações:

1. Validade da referência: todo ID de citação gerado existe na lista de permissões da requisição.
2. Resolução dos metadados: todo ID aponta para um documento, uma página e um trecho de texto armazenado.
3. Suporte da evidência: um revisor ou verificador separado confere se a passagem realmente sustenta a afirmação correspondente.
4. Recall da recuperação: mantenha um pequeno conjunto rotulado de perguntas com os documentos e páginas esperados e meça as falhas após mudanças no chunking, nos embeddings ou no reranking.

Mantenha o servidor do modelo, o índice, o armazenamento de objetos, os logs e o monitoramento dentro do mesmo limite de confiança, a menos que sua política permita explicitamente um serviço externo. Desative o registro do corpo das requisições para documentos sensíveis, remova as consultas dos traces sempre que possível e defina prazos de retenção para PDFs enviados e relatórios gerados.

Não reutilize como benchmark local o número de 51,1 segundos divulgado para o Fast mode da Ai2. Esse valor descreve o pipeline completo do Asta, enquanto uma implantação autogerenciada muda a GPU, o sistema de recuperação, o batching, o tamanho do prompt e o caminho de rede. Meça separadamente a recuperação, o reranking, o tempo até o primeiro token, o tempo de geração e o tempo total da requisição.

Faça o diagnóstico por camada

Esse diagnóstico em camadas evita que uma falha de recuperação seja confundida com um problema do modelo e também impede que um desencontro no formato do prompt seja “corrigido” com a inclusão de mais documentos.

Use o AstaBrief 8B quando você quiser um gerador local especializado em relatórios e estiver disposto a assumir a responsabilidade pela qualidade da recuperação, pelo mapeamento das fontes e pela validação. O vLLM resolve o serviço do modelo; ele não oferece busca em documentos, rastreabilidade das citações nem controles de privacidade.

Fontes

• Model card do AstaBrief 8B
• Documentação do servidor compatível com OpenAI do vLLM
• Template de prompt do AstaBrief
• Biblioteca Ai2 ScholarQA
• Anúncio da Ai2 sobre o AstaBrief