AstaBrief 8B를 vLLM으로 로컬 배포해 비공개 RAG 구축하기

AstaBrief 8B는 검색기가 아닙니다. 연구 질문과 함께 전달한 과학 문헌 발췌문을 바탕으로, 출처를 인용한 보고서를 작성하는 모델입니다. 이 경계를 명확히 이해하는 것이 비공개 배포의 출발점입니다. 생성 모델은 방화벽 안에서 실행하고, 문서 파싱과 검색도 내부 환경에서 처리한 뒤, 순위가 매겨진 근거와 변하지 않는 출처 ID만 모델에 전달해야 합니다.

AstaBrief 8B에 실제로 필요한 것

AstaBrief 8B는 Ai2가 공개한 80억 개 파라미터 규모의 텍스트 생성 모델로, Qwen3-8B를 기반으로 하며 Apache 2.0 라이선스로 배포됩니다. 공식 모델 카드가 정의하는 입력은 연구 질문과 검색된 과학 문헌 발췌문입니다. 모델이 질문을 받아 직접 문헌을 검색하는 구조가 아닙니다. 또한 파인튜닝에 사용된 프롬프트나 상호작용 형식을 바꾸면 출력 품질이 떨어지거나 동작이 일관되지 않을 수 있다고 안내합니다.

이 가이드에서는 최종 allenai/AstaBrief_8B 체크포인트를 사용합니다. 모델 카드의 예제에는 지도 파인튜닝 이전 단계인 allenai/AstaBrief_8B_SFT가 등장합니다. 따라서 다운로드할 체크포인트와 문서에 적힌 이름이 다르다는 점을 먼저 확인해야 합니다. 두 모델을 아무 검증 없이 서로 바꿔 쓸 수 있다고 가정해서는 안 됩니다.

Ai2의 공개 ScholarQA 저장소는 검색, 선택적 리랭킹, 논문 단위 집계, 인용문 추출, 보고서 생성을 각각 별도 구성 요소로 나누는 참조 설계를 이해하는 데 유용합니다. 내부 인덱스로 Semantic Scholar를 대체하더라도, 비공개 구현에서는 이 분리를 유지하는 편이 좋습니다.

재현 가능한 로컬 아키텍처

비공개 파이프라인은 다음 여섯 단계를 명확히 분리해야 합니다.

1. 수집: PDF를 파싱하고 스캔 문서는 OCR 처리합니다. 문서 ID, 제목, 페이지, 섹션, 문자 오프셋도 함께 보존합니다.
2. 청킹: 텍스트를 적당한 크기의 구간으로 나누되 페이지 경계와 제목은 버리지 않습니다.
3. 검색: 용어, 식별자, 정확한 구문이 중요한 경우 키워드 검색과 임베딩 검색을 결합합니다.
4. 리랭킹: 1차 검색 결과를 전체 질문과 비교해 점수를 다시 매기고, 소수의 근거만 남깁니다.
5. 구성: 변경할 수 없는 인용 ID를 부여하고, AstaBrief가 기대하는 참고문헌 형식에 맞춰 발췌문을 구성합니다.
6. 생성: 완성한 프롬프트를 로컬 vLLM 엔드포인트로 전송합니다.

중요한 설계 포인트는 특정 벡터 데이터베이스를 선택하는 일이 아닙니다. 모델에 전달되는 모든 구간에, 애플리케이션이 원문 문서와 페이지로 되돌아갈 수 있는 안정적인 ID를 붙이는 것이 핵심입니다.

인용 ID는 항상 일정하게 유지하기

배열의 위치 대신 DOC_014_P07_A 같은 ID를 사용하세요. 검색 설정이 바뀌면 배열 순서는 달라지지만, 문서·페이지·구간을 조합한 ID는 감사 추적에 활용할 수 있습니다.

매핑 정보는 프롬프트 외부에 저장합니다.

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

프롬프트에서는 발췌문 옆에 같은 ID를 표시합니다. 생성이 끝난 뒤에는 제공한 ID 목록에 없는 인용이 있으면 거부하거나 검토 대상으로 표시하세요. 이렇게 해도 인용된 구절이 모든 주장을 뒷받침한다는 보장은 없지만, 가장 단순한 형태의 인용 조작은 막을 수 있습니다.

컨텍스트를 구성하기 전에 검색 범위 정하기

일치하는 청크를 전부 컨텍스트에 밀어 넣어서는 안 됩니다. 먼저 재현율을 확보할 수 있을 만큼 넓게 검색한 뒤 리랭킹하고, 모델의 프롬프트 예산 안에서 질문에 직접 답하는 구간만 구성해야 합니다. 같은 페이지의 인접 청크를 합쳤을 때 논리가 더 완전해진다면 병합할 수 있습니다. 다만 최종 보고서에서 페이지 단위 추적이 필요하다면 ID는 분리해 두세요.

Ai2 ScholarQA 저장소에는 256개의 후보를 검색한 뒤 리랭킹하고, 논문 단위 결과 50개를 남기는 참조 설정이 소개되어 있습니다. 하지만 이 값은 해당 공개 파이프라인에 적용되는 설정일 뿐, 모든 AstaBrief 배포에 필요한 보편적인 기준은 아닙니다. 먼저 규모가 작은 비공개 문서 모음에서 시작하고, 누락된 근거를 직접 확인하면서 검색 범위와 컨텍스트 한도를 조정하세요.

vLLM으로 AstaBrief 8B 서비스하기

공식 자료에는 데이터 형식, 컨텍스트 길이, 동시 요청 수에 따라 달라지는 VRAM 요구량을 하나의 값으로 제시하지 않습니다. 우선 체크포인트를 로드할 수 있는 하드웨어에서 비양자화 모델로 시작하세요. 이후 양자화 빌드를 검토하기 전에 동시성이나 컨텍스트 길이를 줄여 보십시오. 양자화가 인용 동작을 그대로 보존한다고 가정하지 말고, 실제 문서 모음으로 테스트해야 합니다.

CUDA와 PyTorch 스택에 맞는 깨끗한 환경에 vLLM을 설치합니다. 그런 다음 최종 체크포인트로 OpenAI 호환 서버를 실행합니다.

pip install -U vllm openai

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

--max-model-len 값은 운영상 허용되는 상한입니다. 모든 요청에 16,000토큰을 넣어야 한다는 뜻은 아닙니다. 모델 카드는 학습 최대 길이로 16,000토큰을 제시하지만, 예제에서는 생성 최대치를 max_tokens=4096으로 설정합니다.

로컬 엔드포인트 확인하기

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

그다음 파인튜닝 데이터에서 사용한 것과 동일한 프롬프트 형식으로 요청을 보내세요. 공식 예제는 temperature 0.7, top-p 0.95, 최대 생성 토큰 수 4,096을 사용하며, 토크나이저의 EOS 토큰을 중단 조건으로 지정합니다.

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)

비공개 서버라면 루프백 주소나 내부 인터페이스에 바인딩하고, 게이트웨이에서 인증과 TLS를 처리하며, 외부에서 들어오는 트래픽은 차단하세요. 모델을 로컬에서 실행한다고 해서 로그, 임시 PDF 파일, 트레이싱 데이터까지 자동으로 비공개가 되는 것은 아닙니다.

비공개 검색 요청 구성하기

다음 골격은 인덱스 구현을 의도적으로 열어 둔 예제입니다. 중요한 부분은 순위가 매겨진 근거 목록, 변경할 수 없는 ID, 그리고 프롬프트 경계입니다.

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

실서비스에서는 공식 AstaBrief 프롬프트 템플릿을 사용하고, 참고문헌 ID를 유지한 채 검색된 발췌문을 삽입하세요. 위의 축약된 지시문은 vLLM 연동 방식을 보여 주기 위한 예제일 뿐, 파인튜닝 형식을 대신할 수는 없습니다.

비공개 인덱스에는 BM25, dense retrieval, 하이브리드 검색 중 무엇이든 사용할 수 있습니다. 다만 모든 단계에서 메타데이터를 유지해야 합니다. 문서 ID와 페이지 번호가 없는 구간은 생성된 문장이 아무리 그럴듯해도 방어 가능한 연구 보고서의 근거로 충분하지 않습니다.

운영 전 인용 및 개인정보 보호 게이트 추가하기

AstaBrief가 ScholarQA-CS2에서 보고한 결과는 참고 자료일 뿐, 여러분의 문서 모음에 대한 보증이 아닙니다. 모델 카드의 100개 질문 테스트 세트에서 AstaBrief 8B의 인용 정밀도는 90.5, 인용 재현율은 78.2이며 답변 정밀도는 89.0으로 보고되었습니다. 인용 재현율이 정밀도보다 낮다는 점은 실무적으로 중요합니다. 제공된 자료를 정확히 인용하면서도 관련 근거 일부를 빠뜨리는 보고서가 나올 수 있기 때문입니다.

다음 네 가지 검사를 포함한 게이트를 두세요.

1. 참조 유효성: 생성된 모든 인용 ID가 해당 요청의 허용 목록에 존재하는지 확인합니다.
2. 메타데이터 해석: 모든 ID가 문서, 페이지, 저장된 텍스트 구간으로 연결되는지 확인합니다.
3. 근거 뒷받침 여부: 검토자나 별도의 검증기가 해당 구절이 인접한 주장을 실제로 뒷받침하는지 확인합니다.
4. 검색 재현율: 예상 문서와 페이지를 포함한 소규모 라벨링 질문 세트를 유지하고, 청킹·임베딩·리랭킹을 변경할 때 누락률을 측정합니다.

정책상 외부 서비스 사용을 명시적으로 허용한 경우가 아니라면 모델 서버, 인덱스, 오브젝트 스토리지, 로그, 모니터링 시스템을 같은 신뢰 경계 안에 두세요. 민감한 문서에 대해서는 요청 본문 로깅을 끄고, 가능하면 트레이스에서 질문을 마스킹하며, 업로드된 PDF와 생성된 보고서의 보관 기간도 정의해야 합니다.

Ai2가 보고한 51.1초 Fast-mode 수치를 로컬 성능 기준으로 그대로 사용해서는 안 됩니다. 이 수치는 전체 Asta 파이프라인을 대상으로 한 값이며, 자체 호스팅 환경에서는 GPU, 검색 시스템, 배치 처리, 프롬프트 길이, 네트워크 경로가 달라집니다. 검색, 리랭킹, 첫 토큰까지의 시간, 생성 시간, 전체 요청 시간을 각각 따로 측정하세요.

계층별로 배포 문제 진단하기

이처럼 계층을 나눠 진단하면 검색 누락을 모델 문제로 잘못 판단하는 일을 줄일 수 있습니다. 반대로 프롬프트 형식이 잘못된 상황에서 문서를 더 추가하는 식으로 문제를 해결하려는 것도 막을 수 있습니다.

로컬에서 특화된 보고서 생성기를 운영하고, 검색 품질과 출처 매핑, 검증을 직접 관리할 준비가 되어 있다면 AstaBrief 8B를 고려할 만합니다. 다만 vLLM이 해결하는 것은 모델 서빙뿐입니다. 문서 검색, 인용 출처 추적, 개인정보 보호 제어 기능까지 제공하지는 않습니다.

출처

• AstaBrief 8B 모델 카드
• vLLM OpenAI 호환 서버 문서
• AstaBrief 프롬프트 템플릿
• Ai2 ScholarQA 라이브러리
• AstaBrief에 관한 Ai2 발표