Özel RAG için AstaBrief 8B’yi vLLM ile Yerelde Çalıştırma

AstaBrief 8B bir bilgi erişim modeli değil; araştırma sorusunu ve kendisine verilen bilimsel alıntıları, kaynak gösterilen bir rapora dönüştürüyor. Özel bir kurulum için kritik sınır da burada başlıyor: üretim modelini güvenlik duvarınızın arkasında çalıştırın, belge ayrıştırma ve aramayı yerel tutun, modele yalnızca sıralanmış kanıtları ve değişmeyen kaynak kimliklerini gönderin.

AstaBrief 8B’nin gerçekten ihtiyaç duyduğu şey

AstaBrief 8B, Ai2 tarafından geliştirilen 8 milyar parametreli bir metin üretim modeli. Qwen3-8B tabanlı ve Apache 2.0 lisansıyla yayımlandı. Resmî model kartında modelin girdisi, kendi başına arama yapan bir soru-cevap sistemi olarak değil, bir araştırma sorusu ve erişilen bilimsel literatür alıntıları olarak tanımlanıyor. Belgede ayrıca, ince ayar sırasında kullanılan istem veya etkileşim biçiminin değiştirilmesinin performansı düşürebileceği ve tutarsız çıktılara yol açabileceği konusunda uyarı bulunuyor.

Bu rehberde son allenai/AstaBrief_8B kontrol noktasını kullanın. Model kartındaki örnekte yer alan allenai/AstaBrief_8B_SFT ise denetimli ince ayarın önceki sürümü. İndireceğiniz kontrol noktasını doğrularken bu ad farkını bir dokümantasyon ayrıntısı olarak ele alın; iki modeli birbirinin yerine kullanılabilir varsaymayın.

Ai2’nin herkese açık ScholarQA deposu referans mimariyi anlamak için iyi bir kaynak: erişim, isteğe bağlı yeniden sıralama, makale düzeyinde gruplama, alıntı çıkarma ve rapor üretimi ayrı bileşenler olarak tasarlanmış. Semantic Scholar yerine kurum içi bir indeks kullansanız bile özel kurulumunuzda bu ayrımı koruyun.

Tekrarlanabilir bir yerel mimari kurun

Özel bir hattın altı açık aşaması olmalı:

1. İçe aktarma: PDF’leri ayrıştırın, taranmış sayfalarda OCR uygulayın; belge kimliği, başlık, sayfa, bölüm ve karakter konumlarını koruyun.
2. Parçalama: Metni orta boyutlu bölümlere ayırın; sayfa sınırlarını ve başlıkları kaybetmeyin.
3. Erişim: Terimler, tanımlayıcılar veya tam ifadeler önemli olduğunda sözcüksel aramayı gömme tabanlı aramayla birleştirin.
4. Yeniden sıralama: İlk aşamadaki adayları sorunun tamamına göre puanlayın ve küçük bir kanıt kümesi tutun.
5. Birleştirme: Değiştirilemez alıntı kimlikleri atayın ve alıntıları AstaBrief’in beklediği referans yapısında biçimlendirin.
6. Üretim: Birleştirilmiş istemi yerel vLLM uç noktasına gönderin.

Buradaki asıl tasarım kararı belirli bir vektör veritabanı seçmek değil. Önemli olan kanıt sözleşmesi: modele gönderilen her pasaj, uygulamanızın belgeye ve sayfaya geri eşleyebileceği değişmez bir kimlik taşımalı.

Alıntı kimliklerini sabit tutun

Dizi konumları yerine DOC_014_P07_A gibi kimlikler kullanın. Erişim ayarları değiştiğinde dizi konumları da değişir; belge-sayfa-aralık temelli bir kimlik ise denetlenebilirliğini korur.

Eşlemeyi istemin dışında saklayın:

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

İstemde aynı kimliği alıntının yanında gösterin. Üretimden sonra, gönderilen kimlik kümesinde bulunmayan alıntıları reddedin veya işaretleyin. Bu kontrol, alıntılanan pasajın her iddiayı desteklediğini kanıtlamaz; ancak en basit alıntı uydurma biçimini engeller.

Bağlamı oluşturmadan önce erişim derinliğini belirleyin

Eşleşen her parçayı bağlama doldurmayın. Geri çağırmayı yüksek tutacak kadar geniş arayın, ardından yeniden sıralama uygulayın ve yalnızca modelin istem bütçesine sığan, soruyu doğrudan yanıtlayan pasajları pakete alın. Eksiksiz bir argümanı koruyorsa aynı sayfadaki bitişik parçaları birleştirebilirsiniz; ancak nihai raporda sayfa düzeyinde izlenebilirlik gerekiyorsa kimlikleri ayrı tutun.

Ai2 ScholarQA deposunda, 256 adayın getirildiği, yeniden sıralandığı ve makale düzeyinde 50 sonucun korunduğu bir referans yapılandırması anlatılıyor. Bu değerler genel bir AstaBrief gereksinimi değil, söz konusu herkese açık hattın ayarlarıdır. Özel koleksiyonlarda daha küçük değerlerle başlayın; kaçırılan kanıtları inceleyin ve erişimle bağlam sınırlarını kendi sorularınıza göre ayarlayın.

AstaBrief 8B’yi vLLM ile sunun

Resmî materyaller, her veri türü, bağlam uzunluğu ve eşzamanlılık seviyesi için geçerli tek bir VRAM gereksinimi yayımlamıyor. Önce belleğe sığdırabileceğiniz donanımda nicelemesiz kontrol noktasıyla başlayın. Nicelemeli bir yapıya geçmeden önce eşzamanlı istek veya bağlam uzunluğunu azaltmayı deneyin; nicelemenin alıntı davranışını değiştirmediğini kendi veri kümenizde test etmeden varsaymayın.

vLLM’yi CUDA ve PyTorch yığınınızla uyumlu, temiz bir ortama kurun. Ardından OpenAI uyumlu sunucuyu son kontrol noktasıyla başlatın:

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 değeri operasyonel bir üst sınırdır; her isteğin 16.000 token içermesi gerektiği anlamına gelmez. Model kartında eğitim için en fazla 16.000 token bildiriliyor, ancak örnekte üretim için max_tokens=4096 kullanılıyor.

Yerel uç noktayı doğrulayın

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

Ardından modeli, ince ayar verilerinde kullanılan istem biçimiyle çağırın. Resmî örnekte sıcaklık 0.7, top-p 0.95, en fazla 4.096 üretilen token ve durdurma koşulu olarak tokenizer’ın EOS token’ı kullanılıyor.

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)

Özel bir sunucuda loopback veya kurum içi bir arayüze bağlanın; kimlik doğrulama ve TLS’yi ağ geçidinizde sonlandırın ve dışarıdan gelen erişimi engelleyin. Yerel model kullanmak, günlükleri, geçici PDF dosyalarını veya izleme kayıtlarını kendiliğinden özel hâle getirmez.

Özel erişim isteğini oluşturun

Aşağıdaki iskelet, indeks uygulamasını özellikle açık bırakıyor. Kritik noktalar sıralanmış kanıt listesi, değişmez kimlikler ve istem sınırıdır.

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

Üretim ortamında resmî AstaBrief istem şablonunu kullanın ve erişilen alıntıları referans kimliklerini koruyarak bu şablona yerleştirin. Yukarıdaki kısaltılmış talimat vLLM entegrasyonunu gösterir; ince ayar biçiminin yerini tutmaz.

Özel indeksiniz BM25, yoğun erişim veya hibrit bir yöntem kullanabilir. Tüm aşamalarda üstveriyi koruyun. Belge kimliği ve sayfa numarası bulunmayan bir pasaj, üretilen metin doğru gibi görünse bile savunulabilir bir araştırma raporu için yeterli değildir.

Üretimden önce alıntı ve gizlilik kontrolü ekleyin

AstaBrief’in raporlanan ScholarQA-CS2 sonuçları yararlı bir referanstır; ancak kendi veri kümeniz için garanti sunmaz. Model kartındaki 100 soruluk test kümesinde AstaBrief 8B, alıntı hassasiyetini 90.5, alıntı geri çağırmasını 78.2 ve yanıt hassasiyetini 89.0 olarak bildiriyor. Alıntı geri çağırmasının hassasiyetten düşük olması pratik bir uyarı: rapor, verilen materyali doğru biçimde kaynak gösterebilir ama ilgili kanıtların bir bölümünü yine de atlayabilir.

Dört kontrolden oluşan bir geçiş kapısı kullanın:

1. Referans geçerliliği: Üretilen her alıntı kimliği, isteğin izin verilenler listesinde bulunmalı.
2. Üstveri çözümleme: Her kimlik bir belgeye, sayfaya ve saklanan metin aralığına çözümlenmeli.
3. Kanıt desteği: Bir gözden geçiren veya ayrı bir doğrulayıcı, pasajın gerçekten yakındaki iddiayı destekleyip desteklemediğini kontrol etmeli.
4. Erişim geri çağırması: Beklenen belge ve sayfaları içeren, etiketlenmiş küçük bir soru kümesi tutun; parçalara ayırma, gömmeler veya yeniden sıralamadaki değişikliklerden sonra kaçırılan sonuçları ölçün.

Politikanız açıkça harici bir hizmete izin vermiyorsa model sunucusunu, indeksi, nesne depolamayı, günlükleri ve izlemeyi aynı güven sınırı içinde tutun. Hassas belgeler için istek gövdesi günlüklerini devre dışı bırakın, mümkün olduğunda sorguları izlerden maskeleyin ve yüklenen PDF’lerle üretilen raporlar için saklama süresini tanımlayın.

Ai2’nin bildirdiği 51.1 saniyelik Fast-mode değerini yerel karşılaştırma ölçütünüz olarak kullanmayın. Bu sayı uçtan uca Asta hattını tanımlıyor; kendi barındırdığınız kurulumda GPU, erişim sistemi, gruplama, istem uzunluğu ve ağ yolu değişir. Erişimi, yeniden sıralamayı, ilk token’a kadar geçen süreyi, üretim süresini ve toplam istek süresini ayrı ayrı ölçün.

Kurulum sorunlarını katman bazında giderin

Bu katmanlı yaklaşım, bir erişim hatasının model arızası sanılmasını ve istem biçimi uyumsuzluğunun daha fazla belge eklenerek çözülmeye çalışılmasını engeller.

Özel bir yerel rapor üreticisine ihtiyaç duyuyor ve erişim kalitesini, kaynak eşlemesini ve doğrulamayı kendiniz yönetmeye hazırsanız AstaBrief 8B’yi kullanın. vLLM model sunumunu çözer; belge araması, alıntı kökeni veya gizlilik kontrolleri sağlamaz.

Kaynaklar

• AstaBrief 8B model kartı
• vLLM OpenAI uyumlu sunucu dokümantasyonu
• AstaBrief istem şablonu
• Ai2 ScholarQA kütüphanesi
• Ai2’nin AstaBrief duyurusu