Qwen-VL-OCR API ile görselden metin: sürüm ve bölge seçimi

Görselden metin için hangi kimlik kullanılmalı?

Qwen-VL-OCR ile görselden metin çıkarmak için LLMTR üzerinde qwen/qwen-vl-ocr modelini, /v1/chat/completions yolunu ve image_url içerik parçasını kullanın. Görseli bir user mesajında, ne okunacağını söyleyen kısa bir metinle birlikte gönderin. Ayrı bir OCR uç noktası aramanız gerekmez.

Sağlayıcı tarafındaki model adı qwen-vl-ocr şeklindedir. Alibaba doküman adresinde görülen qwenvl-ocr ise sayfanın URL parçasıdır; model alanına kopyalanmamalıdır. LLMTR kimliğindeki qwen/ öneki de doğrudan Alibaba isteğinin parçası değildir. Bu üç yazımı ayırmak, ilk istekteki gereksiz kimlik hatalarını önler.

Bölgeyi ve tarihli sürümü ayrı doğrulayın

Doğrudan Alibaba Model Studio kullanıyorsanız hesabınızın eriştiği bölge, o bölgenin uç noktası ve desteklenen model adı birlikte kontrol edilmelidir. LLMTR kullanırken kendi LLMTR temel adresinizi koruyun; sağlayıcının bölgesel adresini buraya yapıştırmak bağlantıyı ve gereken anahtarı değiştirir.

28 Ağustos 2026 tarihinde incelenen resmî model kartı tarihli sürümleri ve bölgesel koşulları ayrı gösteriyor. Ancak bu bilgi, LLMTR'nin canlı bağlantısının aynı tarihli sürüme sabitlendiğini kanıtlamaz. Yeniden üretilebilirlik gerekiyorsa kullanılan sürümü ve bölgeyi ayrıca teyit edin; model adına tahminle tarih eklemeyin.

İlk görüntüyü güvenli ve okunabilir hazırlayın

Bir metin düzenleyicide DEMO, Lot A17 ve 12 items satırlarını yazın; yalnızca bu alanı içeren bir PNG ekran görüntüsünü ocr-demo.png olarak kaydedin. Bu örnek girdidir, modelin ürettiği veya doğruladığı bir sonuç değildir. Ad, adres, hesap bilgisi, bildirim veya müşteri belgesi içermediğini görsel olarak kontrol edin.

Metin yatay dursun, kenarlar kesilmesin ve karakterler büyütmeden okunabilsin. İlk denemede tek görüntü kullanmak, dosya hazırlama sorunu ile istek biçimi sorununu ayırmayı kolaylaştırır. Base64 veri URL'si yerel dosyayı isteğe ekler; görüntünün sağlayıcıya gönderildiği gerçeğini değiştirmez. Gizli bir belgeyi bu yöntemle göndermeyi güvenli kabul etmeyin.

Python ile tek görüntülü LLMTR isteği

LLMTR_BASE_URL değişkenine kullanacağınız tam API temel adresini, LLMTR_API_KEY değişkenine LLMTR anahtarınızı ortam üzerinden verin. Temel adresin API yolunu zaten içerdiğini kontrol edin; kod yalnızca /chat/completions ekler. Anahtarı koda, kaynak kontrolüne veya günlüklere yazmayın.

Aşağıdaki örnek Python standart kütüphanesini kullanır ve ek paket gerektirmez. Çalıştırıldığında ücretli bir istek gönderebilir; bu rehber hazırlanırken çalıştırılmamıştır. max_tokens değeri kısa deneme için seçilmiş çıktı bütçesidir, modelin üst sınırı değildir. Örnek, çıkan metni bellekte tutar ve içeriği günlüğe yazmaz.

Kişisel veri içermeyen ocr-demo.png dosyasını gönderme

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

image_bytes = Path("ocr-demo.png").read_bytes()
if not image_bytes.startswith(b"\x89PNG\r\n\x1a\n"):
    raise ValueError("ocr-demo.png must be a PNG image")

image_url = "data:image/png;base64," + base64.b64encode(image_bytes).decode("ascii")
payload = {
    "model": "qwen/qwen-vl-ocr",
    "messages": [{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": image_url}},
            {"type": "text", "text": (
                "Read only the visible text. Preserve line breaks. "
                "Mark unreadable characters with ?. Do not guess."
            )}
        ]
    }],
    "max_tokens": 256,
    "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"
)
with urlopen(request, timeout=60) as response:
    result = json.load(response)

choice = result["choices"][0]
if choice.get("finish_reason") != "stop":
    raise RuntimeError("Review the completion status before accepting OCR text")
recognized_text = choice["message"].get("content")
if not isinstance(recognized_text, str) or not recognized_text.strip():
    raise RuntimeError("No OCR text received")
print("OCR response received; text was not logged.")

Sağlayıcı parametrelerini otomatik taşımayın

LLMTR'nin mevcut görüntü mesajı biçimi image_url altında url ve isteğe bağlı detail alanını tanımlar. Alibaba örneklerinde görüntü parçasına eklenen min_pixels ve max_pixels alanlarının aynı biçimde taşınacağını varsaymayın. Bu başlangıç örneğinde onları kullanmayın; gerekiyorsa görüntüyü göndermeden önce hazırlayın.

Benzer şekilde, istemde JSON istemek zorunlu şema garantisi sağlamaz. İlk bağlantı testinde düz metin kullanmak ek bir ayrıştırma hatasını devreden çıkarır. Sonradan alan çıkarımına geçtiğinizde eksik veya okunamayan değerleri bilinmiyor olarak ele alın; modelin kendinden emin bir cümle kurması doğrulama yerine geçmez.

Sürüm değişiminden önce küçük bir kabul testi yapın

Aynı hassas olmayan örneği farklı yazı boyutu, eğiklik ve düşük kontrastla hazırlayın. Beklenen metni kendiniz belirleyin; satır atlama ve karakter karışmasını ayrı değerlendirin. Bir isteğin başarıyla dönmesi, metnin doğru okunduğunu göstermez. Model veya bölge değiştiğinde aynı örneklerle karşılaştırma yapın.

Çıktı kesilmişse tamamlanmış belge gibi kabul etmeyin. Bütçeyi ancak doğrulanmış sınırlar içinde artırın veya görüntüyü anlamlı parçalara ayırın. Fiyat, bağlam, çıktı tavanı ve cache indirimi için farklı sürümlerin değerlerini birleştirmeyin. Bu rehberde canlı dağıtımla eşleşen sayısal koşullar doğrulanmadığından sabit bir maliyet ya da kapasite vaadi verilmemektedir.

Sık sorulan sorular

qwenvl-ocr model alanına yazılabilir mi?

Hayır. Bu yazım doküman adresinde kullanılır. LLMTR isteğinde qwen/qwen-vl-ocr, doğrudan Alibaba isteğinde erişiminize uygun qwen-vl-ocr model adı kullanılır.

LLMTR isteğine region ekleyerek bölge seçebilir miyim?

Bu rehberin doğruladığı sözleşmede kullanıcıya sunulan bir bölge seçici yoktur. Ek bir region alanını bölge garantisi saymayın; ihtiyaç duyduğunuz dağıtım koşullarını LLMTR ile teyit edin.

Bilgisayarımdaki dosyanın yolunu image_url olarak verebilir miyim?

Dosya yolunu doğrudan göndermeyin. Örnek, PNG içeriğini okuyup base64 veri URL'sine çevirir. Uzak bağlantı kullanıyorsanız görüntüye erişim ve paylaşım yetkisini ayrıca kontrol edin.

İlgili yazılar

• Qwen-VL-OCR ile fatura ve tablo okuma: eksik alanları doğrulama
• Muse Spark 1.2’ye görsel ve PDF gönderme: girdi hatalarını teşhis
• OpenAI SDK ile LLMTR'ye geçiş: base_url rehberi

• qwen/qwen-vl-ocr
• Model kataloğu
• Gateway dokümantasyonu
• OpenAI / OpenRouter