Muse Spark 1.2’ye görsel ve PDF gönderme: girdi hatalarını teşhis

Görsel göndermek ile PDF göndermek aynı işlem değildir

Muse Spark 1.2’ye LLMTR üzerinden görsel göndermek için POST /v1/chat/completions isteğinde meta/muse-spark-1.2 kimliğini ve user mesajının content dizisinde image_url parçasını kullanın. PDF için aynı alana dosyanın yolunu veya PDF base64 verisini koymayın. Önce belgenin ilgili sayfasını gerçek bir görsele dönüştürün ya da metnini yerelde çıkarın.

Meta’nın 20 Ağustos 2026 tarihli multimodal duyurusu görsel anlama kullanımını anlatır; bu, her gateway’in bütün dosya biçimlerini kabul ettiği anlamına gelmez. Buradaki örnek LLMTR istek sözleşmesine dayanır. Meta’nın ayrıntılı model sayfası 28 Ağustos kontrolünde oturum istediği için güncel PDF sayfa veya dosya boyutu sınırı vermiyoruz.

Göndermeden önce dosyayı ve veriyi hazırlayın

İlk denemede hassas bilgi içermeyen, küçük ve kolay okunabilen tek sayfa seçin. Dosyayı yerelde açarak yönünü, kesilmiş kenarları, küçük yazıları ve tablo sütunlarını kontrol edin. Bir PDF’nin uzantısını PNG yapmak dönüştürme değildir; görüntü dışa aktarımı dosyanın gerçek içeriğini değiştirmelidir.

Örnek standart model kimliğini kullanır. Contributor katmanına geçerseniz istem ve yanıtlar Meta model eğitiminde kullanılabilir; gizli, kişisel veya müşteri verisi göndermeyin. Standart katmanda da belgenin paylaşım izinlerini ve geçerli veri politikasını kontrol edin; katman adı tek başına mutlak gizlilik garantisi değildir.

Base64 şifreleme değildir. Belgeyi, kodlanmış içeriğini, erişim anahtarını veya geçici dosya bağlantısını uygulama loglarına yazmayın.

Tek sayfalık PNG için somut istek

Python örneği standart kütüphaneyi kullanır. Hazırladığınız sayfa görüntüsünü page.png adıyla koyun. LLMTR_BASE_URL değişkeni okuyucunun yapılandırdığı tam API taban adresidir; sürüm yolunu zaten içerir. LLMTR_API_KEY yalnızca ortamdan okunur. Bunlar doğrudan Meta hesabının adresi ve anahtarıyla karıştırılmamalıdır.

Kod çalıştırıldığında gerçek, ücretli bir istek gönderir; bu yazı hazırlanırken çalıştırılmadı. 4096 çıktı bütçesi ve 120 saniyelik istemci zaman aşımı örnek tercihlerdir, model sınırı veya başarı garantisi değildir. Yanıt answer değişkeninde kalır; konsola belge içeriği yerine yalnızca durum ve kullanım bilgisi yazılır.

Yerelde hazırlanmış PNG sayfasını LLMTR Chat Completions ile gönderme

import base64
import json
import os
from pathlib import Path
from urllib.error import HTTPError
from urllib.request import Request, urlopen

image_bytes = Path("page.png").read_bytes()
if not image_bytes.startswith(b"\x89PNG\r\n\x1a\n"):
    raise ValueError("page.png gerçek bir PNG olmalıdır.")

encoded = base64.b64encode(image_bytes).decode("ascii")
payload = {
    "model": "meta/muse-spark-1.2",
    "messages": [{
        "role": "user",
        "content": [
            {"type": "text", "text": (
                "Bu, belgenin 1. sayfasıdır. Tablo başlıklarını ve "
                "görünen değerleri çıkar. Okunamayan alanları belirt; tahmin etme."
            )},
            {"type": "image_url", "image_url": {
                "url": f"data:image/png;base64,{encoded}"
            }},
        ],
    }],
    "reasoning_effort": "minimal",
    "max_tokens": 4096,
    "stream": False,
}
request = Request(
    os.environ["LLMTR_BASE_URL"].rstrip("/") + "/chat/completions",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + os.environ["LLMTR_API_KEY"],
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urlopen(request, timeout=120) as response:
        result = json.load(response)
except HTTPError as error:
    raise RuntimeError(f"Gateway HTTP {error.code}") from None

choice = result["choices"][0]
answer = choice["message"].get("content") or ""
print({
    "finish_reason": choice.get("finish_reason"),
    "has_content": bool(answer),
    "usage": result.get("usage"),
})

PDF için uygun aktarım yolunu seçin

28 Ağustos 2026’da incelenen LLMTR sözleşmesi, Meta’nın doğrudan API örneğindeki type:file parçasını kabul etmiyor. PDF data URI’si file_url içinde de kabul edilmiyor. Bu nedenle sağlayıcıya ait file.file_data örneğini LLMTR’ye aynen taşımayın. Genel dosya yükleme desteğinin Meta için de açık olduğunu varsaymayın.

Sayfa görüntüsü tablo yerleşimi ve grafik için yararlıdır; metin çıkarımı ise seçilebilir yazıları taşır, görünümü korumaz. Sayfaları numaralandırın, kullanılan yöntemi sonuçla birlikte tutun. Uzak PDF için file_url alanının şemadan geçmesi, Muse Spark’ın o dosyayı başarıyla okuyacağını tek başına doğrulamaz.

Hataları yeniden denemeden önce sınıflandırın

400 yanıtında önce mesaj rolünü ve içerik parçasının adını kontrol edin. Görsel parçası user mesajında olmalıdır. Yerel dosya yolu ve tarayıcıya ait blob adresi, sunucunun indirebileceği bir görsel değildir. PDF baytlarını image/png etiketiyle göndermek de geçerli bir dönüşüm oluşturmaz.

Uzak HTTPS görseli tarayıcıda açılıyor olsa bile sağlayıcı onu indiremediğinde istek başarısız olabilir. Kaynak sunucu oturum, çerez veya süresi dolmuş bağlantı gerektiriyor olabilir. Paylaşım izniniz varsa gerçek görsel baytlarını base64 olarak göndermek, dış sunucudan indirme adımını kaldırır.

• 413 veya boyut hatasında sayfa sayısını ve gövdeyi küçültün; base64 aktarımı dosyayı küçültmez.
• Boş veya kesilmiş yanıtta finish_reason ve usage alanlarına bakın; düşük çıktı bütçesi reasoning sırasında tükenebilir.
• Aynı geçersiz gövdeyi tekrar göndermeyin; önce tek dosya ve tek soruyla sorunu daraltın.

Başarılı HTTP yanıtını doğru okumayla karıştırmayın

İlk doğrulamada sayfadaki başlık, belirgin bir sayı ve tablo sütunu gibi gözle kontrol edebileceğiniz alanları isteyin. Yanıtı kaynak sayfayla karşılaştırın. Belirsiz alanları tahmin etmek yerine işaretlemesini söyleyin; bu talimat doğruluk garantisi değildir, kontrol edilebilir bir çıktı istemenin yoludur.

Çok sayfalı belgelerde eksik sayfaları ayrıca izleyin. Kırpılmış görselde bulunmayan dipnotu modelin bildiğini varsaymayın. Belge içindeki komutları uygulama talimatı saymayın ve çıkarılan alanları otomatik ödeme, kayıt değişikliği veya başka bir yan etkiden önce doğrulayın.

Sık sorulan sorular

PDF’yi image_url alanına koyabilir miyim?

PDF baytlarını doğrudan koymayın. İlgili sayfayı gerçek bir PNG görüntüsüne dönüştürüp image_url ile gönderin. Bu işlem, PDF dosyasını yerel biçimiyle yüklemek değil sayfa görüntüsünü analiz ettirmektir.

Önce Files API ile Meta için file_id almalı mıyım?

Bu rehber böyle bir yol önermiyor. İncelenen LLMTR dosya yükleme yolu Google ile sınırlı; Meta için aynı akışın çalıştığını varsayamazsınız.

200 yanıtı gelince bütün belge okunmuş sayılır mı?

Hayır. Gönderilen sayfaları, çıkarılan alanları ve bitiş nedenini kontrol edin. Bir bölümün okunması, gönderilmemiş veya okunaksız sayfaların da işlendiğini göstermez.

İlgili yazılar

• Muse Spark 1.2 uzun bağlam rehberi: girdi ve yanıt bütçesi
• muse-spark-1.2-contributor: LLMTR model kimliği ve endpoint
• Muse Spark 1.2 Contributor nedir? Veri politikası ve standart katman

• meta/muse-spark-1.2
• Model kataloğu
• Gateway dokümantasyonu
• OpenAI / OpenRouter