GLM-5.3-Flash Vision: 1M Bağlamlı Modele Görüntü Gönderme

GLM-5.3-Flash ile Yerel Görüntü Girdisi: Uygulama Rehberi

Çoğu görüntü modeli görüntü veya uzun metin arasında seçim yapmanızı ister. GLM-5.3-Flash ise görüntüleri, 1.048.576 tokenlık bağlam penceresinde metinle birlikte aynı isteğin içerik blokları olarak işler. Bu rehber; veri yükünü, uygulanabilir iş akışlarını, maliyeti ve doğrulamanız gereken sınırlamaları kapsar.

Apidog'u bugün deneyin

Yerel çok modluluk

Z.ai'nin önceki görüntü modelleri, ayrı model kimlikleri ve uç noktalar kullanıyordu. GLM-5V-Turbo ve GLM-4.6V ile görüntü trafiğini metin trafiğinizden ayrı yönlendirmeniz gerekiyordu. GLM-5.3 ise görüntüleri yerel olarak ele almak yerine adaptörler üzerinden yönlendirir.

GLM-5.3-Flash, GLM-5 serisinde görüntüleri aynı çağrıda ve aynı bağlamı paylaşan modele birinci sınıf girdi olarak alan ilk modeldir.

Bu yaklaşım şunları tekilleştirir:

• Tek model kimliği
• Tek faturalandırma satırı
• Tek oran sınırı seti
• Görüntü ve metni birlikte taşıyan ortak bağlam penceresi

Eski görüntü modellerini kullanıyorsanız, GLM-5V-Turbo API kılavuzuna ve GLM-4.6V kılavuzuna bakın.

Veri yükü

Görüntüler türlenmiş içerik bloklarıyla gönderilir. content alanı bir dize yerine dizi olmalıdır:

from openai import OpenAI
import os

client = OpenAI(
    [REDACTED CREDENTIAL]_API_KEY"],
    base_url="https://api.z.ai/api/paas/v4/",
)

response = client.chat.completions.create(
    model="glm-5.3-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Bu düzende mobilde sorun ne?"},
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/mobile-view.png"},
                },
            ],
        }
    ],
)

print(response.choices[0].message.content)

Yerel veya özel görüntüler için base64 veri URL'si kullanın:

import base64
from pathlib import Path

def image_block(path: str) -> dict:
    data = base64.b64encode(Path(path).read_bytes()).decode("utf-8")
    suffix = Path(path).suffix.lstrip(".").replace("jpg", "jpeg")
    return {
        "type": "image_url",
        "image_url": {"url": f"data:image/{suffix};base64,{data}"},
    }

Birden fazla görüntü için her görüntüyü ayrı blok olarak ekleyin:

content = [
    {"type": "text", "text": "Resim 1 tasarımdır. Resim 2 bizim oluşturduğumuzdur. Farklılıkları listeleyin."},
    image_block("design.png"),
    image_block("built.png"),
]

Blok sırası önemlidir. Model diziyi sırayla okur; bu nedenle açıklayıcı metni görüntülerden önce verin ve çoklu görüntüleri açıkça etiketleyin.

Kimlik doğrulama ve temel kurulum için GLM-5.3-Flash API kılavuzunu kullanın.

İnşa etmeye değer iş akışları

Ekran görüntüsü hata ayıklama

Z.ai, modelin “arayüzleri, render sonuçlarını ve etkileşim geri bildirimlerini” gözlemleyebildiğini belirtiyor. Hatalı render'ı ve kaynak kodu aynı çağrıda gönderin:

content = [
    {"type": "text", "text": "Bu bileşen 400 pikselin altında yanlış render ediliyor. İşte ekran görüntüsü ve kaynak kodu."},
    image_block("bug-mobile.png"),
    {"type": "text", "text": f"```
{% endraw %}
jsx\n{component_source}\n
{% raw %}
```"},
]

Bu yaklaşım, insanın görsel sorunu metne çevirmesi gereken kayıplı adımı kaldırır. Model, açıklamanız yerine gerçek render üzerinden değerlendirme yapar.

Tasarım karşılaştırması

İki görüntü ve net bir karşılaştırma sorusu gönderin. Bu yöntem, görsel regresyon testlerinde yumuşak bir CI kontrolü olarak kullanılabilir:

• Piksel farkı aracınız değişikliği tespit eder.
• Model, değişikliğin kullanıcı açısından anlamlı olup olmadığını değerlendirmeye yardımcı olur.
• İnsan incelemesini önceliklendirmek için kullanın.
• Tek başına dağıtımı engelleyen karar mekanizması olarak kullanmayın.

Belgeler ve şartnameler

1 milyon tokenlık bağlam penceresi burada anlam kazanır: uzun bir şartnameyi metin olarak, oluşturulmuş yapıtı ise görüntü olarak aynı prompt'a ekleyin.

content = [
    {"type": "text", "text": f"Şartname:\n\n{spec_text}"},
    {"type": "text", "text": "Aşağıda oluşturulan rapor bulunmaktadır. Yukarıdaki her gereksinimi karşılıyor mu? Eksikleri listeleyin."},
    image_block("generated-report.png"),
]

40 sayfalık bir şartnameyi ve tek görüntüyü aynı prompt'ta değerlendirmek, 128K bağlam penceresi ve adaptör tabanlı görüntü desteğiyle mümkün değildir. Bu, modelin gerçek yeni yeteneğidir.

Z.ai'nin sürüm notları; ofis belgeleri ve finansal araştırma iş akışlarını da modelin ajan davranışı için hedef alanlar olarak belirtir.

Grafikler ve panolar

Grafik görüntüsünden yapılandırılmış veri çıkarmak için yalnızca JSON isteyin:

content = [
    {"type": "text", "text": "Bu grafikteki serileri JSON olarak çıkarın: [{label, values: [...]}]. Sadece JSON döndürün."},
    image_block("quarterly.png"),
]

Çıktıyı bir şemaya göre doğrulayın. Şema, değerlerin doğru olduğunu kanıtlamaz; ancak yanlış biçim veya beklenmeyen yapıdaki çıktıları yakalar. Sayısal doğruluk kritikse, veriyi görüntü yerine temel veri kaynağından alın.

Özel belge çıkarma gereksinimleri için belge anlama amacıyla GLM-OCR daha uygun olabilir.

Video ve dosyalar

Z.ai dokümantasyonu, görüntülere ek olarak video ve dosya girdisini de aynı içerik bloğu mekanizmasıyla listeler.

Ancak bunu doğrudan üretim özelliği olarak kabul etmeyin:

1. Video desteği yeni ve az belgelenmiştir.
2. Görüntü girişi, video girişine göre daha yaygın test edilmiştir.
3. Sağlayıcı ve ağ geçidi desteği değişebilir.
4. Modelin teorik yeteneği, kullandığınız uç noktada mevcut olduğu anlamına gelmez.

Video kritikse, tasarımı kesinleştirmeden önce kendi medyanız ve sağlayıcınızla uçtan uca test yapın.

Bilinen hata modları

Yerel çok modluluk, güvenilir çok modluluk anlamına gelmez.

Grafiklerden gelen kendinden emin sayılar. Çizilmiş bir grafikten değer okumak, akıcı ve hassas görünümlü ama yanlış cevap üretmeye yatkındır. Şema doğrulaması biçim hatalarını yakalar; makul görünen yanlış sayıları yakalayamaz.

Küçük metin. Yoğun UI ekran görüntüleri, düşük çözünürlüklü tablolar ve sıkıştırılmış kod görselleri kaliteyi düşürür. Tüm görüntüyü küçültmek yerine ilgili alanı kırpın.

Uzamsal hassasiyet. Model düzen sorunlarını iyi tanımlar, ancak piksel hassasiyetinde ölçüm yapmaz. “Düğme girişin üzerine biniyor” güvenilir olabilir; “düğme 12 piksel çok solda” güvenilir değildir.

Sıra ve referans karışıklığı. Birden fazla görüntüde model bir ayrıntıyı yanlış görüntüye atfedebilir. Görüntüleri metin bloklarında açıkça etiketleyin ve hassas işlerde görüntü sayısını düşük tutun.

Bu sınırlamalar GLM-5.3-Flash'e özgü değildir. Görüntü dil modellerinin genel sınırlamalarıdır; 57 İstihbarat Endeksi puanı bunu değiştirmez. İş akışınızı, yanlış yanıtların otomatik olarak eyleme geçirilmek yerine yakalanacağı şekilde kurun.

Maliyet

Görüntüler bağlam tokenı tüketir ve girdi olarak faturalandırılır; ayrı bir görüntü ek ücreti yoktur.

Liste fiyatına göre bir milyon girdi tokenı 0,15 ABD dolarıdır. 9 Eylül 2026'ya kadar geçerli lansman indirimiyle fiyat 0,075 ABD dolarıdır. Yüksek çözünürlüklü görüntüler çok sayıda token tüketebileceğinden, çözünürlük doğrudan maliyet kaldıraçlarından biridir.

reasoning_effort varsayılan olarak max değerindedir; akıl yürütme çıktı tokenı olarak faturalandırılır. Basit görüntü çıkarma işlemlerinde low çoğunlukla yeterlidir ve daha ucuzdur. Ayrıntılar için fiyatlandırma dökümünü inceleyin.

Görüntü maliyetlerini kontrol etme

Maliyeti azaltırken doğruluğu korumak için:

• Ölçeklemeden önce kırpın. İlgili alanı tam çözünürlükte göndermek, tüm ekranı küçültmekten daha iyidir.
• Çözünürlüğü soruya göre seçin. “Düzen bozuk mu?” agresif küçültmeye dayanabilir; “Bu hata mesajı ne diyor?” dayanmaz.
• Değişmeyen görüntüleri yeniden göndermeyin. Çok turlu konuşmada bağlamda bulunan görüntüyü tekrar eklemek, tekrar ücretlendirilmenize neden olur.
• reasoning_effort değerini bilinçli seçin. Basit çıkarma görevleri genellikle max gerektirmez.

Her yanıttaki usage nesnesi, görüntünün gerçek token maliyetini çağrı bazında gösterir. Dosya boyutundan tahmin yürütmek yerine bu değeri izleyin.

Çok modlu çağrıları test etme

Base64 veri URL'leri binlerce karakter uzunluğunda olabilir; bu nedenle çok modlu istekleri curl ile sürdürmek zordur. Serbest biçimli yanıtlar da regresyonları fark etmeyi güçleştirir.

İki pratik alışkanlık uygulayın:

1. Davranış değişikliklerini izlemek için küçük ve sabit bir referans görüntü ile beklenen yanıt kümesi tutun.
2. Yapılandırılmış çıkarma çıktısını gözle incelemek yerine şemaya göre doğrulayın.

Apidog, görüntü yüklerini kaydedilmiş isteklerde saklamanıza, API anahtarlarını ortam değişkeni olarak yönetmenize ve JSON yanıtlarına doğrulama eklemenize yardımcı olur. Modeli veya sağlayıcıyı değiştirdiğinizde paketi yeniden çalıştırarak görüntü yolunun hâlâ doğru çalıştığını doğrulayabilirsiniz.

Sıkça sorulan sorular

GLM-5.3 görüntüleri destekliyor mu? Yerel olarak değil. GLM-5.3, görüntüleri ayrı adaptörler üzerinden yönlendirir. Flash, yerel çok modlu modeldir. Ayrıntılar için karşılaştırmayı inceleyin.

İstek başına kaç görüntü gönderebilirim? Birden fazla görüntü gönderebilirsiniz; her biri kendi image_url bloğu olmalıdır. Pratik sınır, bağlam bütçenizdir.

URL mi, base64 mü kullanmalıyım? Her ikisi de çalışır. Halihazırda barındırılan ve erişilebilir görüntüler için herkese açık URL; yerel veya özel görüntüler için base64 kullanın.

Video kabul ediyor mu? Z.ai video girdisini belgeliyor; ancak özellik yeni ve az test edilmiştir. Önce kendi medyanız ve sağlayıcınızla doğrulayın.

Görüntüler farklı mı faturalandırılıyor? Hayır. Ayrı bir ek ücret yoktur; görüntüler girdi tokenı tüketir. Bu nedenle çözünürlük maliyeti doğrudan etkiler.