Claude'a bir belge verip soru sorduğunuzda, yanıtın belgedeki hangi bölüme dayandığını da görmek isteyebilirsiniz. Citations API bunu sağlar. Gönderdiğiniz belgelerdecitations.enabled=true ayarını açtığınızda Claude, yanıtındaki atıfları kaynak metindeki ilgili bölümlerle eşleştirir.
Citations API nedir, ne işe yarar?
Citations API, Claude'un yanıtındaki atıfları kendisine gönderdiğiniz belgelerdeki ilgili bölümlerle eşleştirir. Özellik, desteklenen Claude modellerinde kullanılabilir.
Bu özellik özellikle RAG sistemlerinde işe yarar. Model, kendisine verilen belgelerden yanıt üretirken belgede bulunmayan bilgiler ekleyebilir. Kaynak metne bağlı atıflar, yanıtı kontrol etmeyi kolaylaştırır ve bu riski azaltmaya yardımcı olur. Hangi ifadenin hangi belgeden geldiğini ayrıca eşleştirmek yerine, API'nin döndürdüğü atıf bilgilerini kullanabilirsiniz.
Buradaki "atıf alma", Claude'un genel yanıtlarında web sitenizi kaynak göstermesi anlamına gelmez. Citations API, kendi uygulamanızda Claude'a gönderdiğiniz belgelere atıf yapılmasını sağlar. 24 Ocak 2025 tarihli kaynakta anlatılan kullanım da Claude.ai arayüzüne değil, geliştiricilerin API üzerinden kurduğu entegrasyona yöneliktir.
Citations API nasıl kullanılır?
Dört adımda: belge formatını seçin, atıf özelliğini tüm belgelerde açın, belgeleri ve sorunuzu gönderin, yanıttaki atıfları işleyin.
1. Belge formatını seçin
PDF, düz metin veya özel içerik blokları gönderebilirsiniz. Seçtiğiniz format, atıf yapılan bölümün yanıtta nasıl belirtileceğini belirler.
| Belge formatı | Atıf konumu | Bölümleme |
|---|---|---|
| 1'den başlayan sayfa numaraları | Metin cümle bazında bölümlenir. | |
| Düz metin | 0'dan başlayan karakter indeksleri | Başlangıç ve bitiş aralığı belirtilir. |
| Özel içerik | 0'dan başlayan blok indeksleri | Verdiğiniz bloklar kullanılır; ek bölümleme yapılmaz. |
Belgeleri, desteklenen formata göre base64, metin veya URL olarak iletebilirsiniz. Files API kullanıyorsanız belgeyi file_id üzerinden de gönderebilirsiniz.
2. Atıf özelliğini tüm belgelerde açın
Her belge nesnesine citations: {"enabled": true} alanını ekleyin.
Bu ayarın istekteki tüm belgelerde aynı olması gerekir. Bir belgede atıfları açıp diğerinde kapalı bırakırsanız API hata döndürür. Yani atıf özelliği ya bütün belgelerde açık ya da bütün belgelerde kapalı olmalıdır.
3. Belgeleri ve sorunuzu gönderin
Hangi belgelerin kullanılacağını siz seçersiniz. Citations API, soruya uygun belgeleri kendiliğinden bulup getirmez; kendisine gönderilen içerikler üzerinden çalışır.
Anthropic'in Python istemci kütüphanesinde Citations desteği bulunur. Bu nedenle özelliği kullanmak için ayrı bir paket kurmanız gerekmez.
4. Yanıttaki atıfları işleyin
Yanıttaki metin bloklarında citations alanı bulunabilir. Bu alan, alıntılanan metni ve metnin kaynak belgedeki konumunu içerir.
Düz metin belgelerine yapılan atıflarda cited_text, document_index, document_title, start_char_index, end_char_index ve type gibi alanlar yer alır. Bu atıfların türü char_location olarak belirtilir. PDF ve özel içerik bloklarında ise konum bilgisi, kullanılan belge formatına göre değişir.
Belgeye eklediğiniz title ve context alanları da modele iletilir. Ancak bu alanlar, doğrudan atıf yapılabilecek kaynak metnin parçası sayılmaz.
Maliyet ve performans açısından bilmeniz gerekenler
Atıflardaki cited_text alanı çıktı token hesabına dahil edilmez. Aynı metni sonraki konuşma turlarında atıf nesnesi içinde geri gönderdiğinizde de bu alan için girdi token'ı hesaplanmaz. Özellikle çok sayıda alıntı içeren yanıtlarda bu ayrım maliyet hesabını etkileyebilir.
Yine de atıf özelliğinin hiç ek maliyet getirmediğini düşünmemek gerekir. Sisteme eklenen talimatlar ve belgelerin bölümlenmesi, girdi token sayısını bir miktar artırır.
Prompt caching kullanıyorsanız kaynak belgeleri önbelleğe alabilirsiniz; atıf bloklarını ise doğrudan önbelleğe alamazsınız. Bunun için cache_control ayarını üst düzey belge içerik bloklarına eklemeniz gerekir. Citations, token sayımı ve toplu işlem özellikleriyle de kullanılabilir.
PDF gönderirken belgenin metin katmanını kontrol edin. Yalnızca taranmış sayfa görüntülerinden oluşan ve metni çıkarılamayan PDF'ler, doğrudan atıf kaynağı olarak kullanılamaz.
Sıkça Sorulan Sorular
Aynı istekte bazı belgelerde atıfları açıp diğerlerinde kapatabilir miyim?
Hayır. Atıf ayarı, istekteki tüm belgeler için aynı olmalıdır. Bir belgeyi atıf kapsamına almak istemiyorsanız o belgeyi isteğe dahil etmeyebilirsiniz.
Görsellere veya taranmış PDF'lere atıf yapılabilir mi?
Citations, metin tabanlı atıfları destekler. Metin katmanı bulunmayan, yalnızca görüntüden oluşan PDF'lerde doğrudan kullanılamaz.
Streaming yanıtlarında atıflar nasıl gelir?
Atıflar, content_block_delta olayları içinde citations_delta türüyle iletilir. Her olay tek bir atıf taşır. Uygulamanızda bu atıfları geldikçe biriktirebilir ve ilgili yanıt metniyle birlikte gösterebilirsiniz.
Citations API hangi platformlarda kullanılabilir?
Anthropic'in doğrudan API'sinin yanı sıra AWS Bedrock, Google Cloud ve Microsoft Foundry üzerinde de desteklenir.
Alıntılanan metin için çıktı token ücreti ödenir mi?
cited_text alanındaki metin, çıktı token sayısına dahil edilmez. Ancak yanıtın geri kalanı ve istekte kullanılan diğer içerikler için normal token hesabı devam eder.
Mevcut istemci kütüphaneme eklemek neden uğraştırabilir?
Bazı istemci kütüphaneleri, modelden gelen yanıtı yalnızca düz metin olarak işler. Citations ise metnin yanında yapılandırılmış atıf bilgileri de döndürür. Kullandığınız kütüphane bu yapıyı desteklemiyorsa atıfları okuyup gösterecek ek kod yazmanız gerekebilir.
Kaynakta ele alınan llm-claude-3 entegrasyonu da bu duruma örnektir. Bu nedenle kullandığınız kütüphanenin ve sürümün Citations desteğini kontrol etmeniz gerekir.
Atıf bulunması, yanıtın doğru olduğu anlamına gelir mi?
Tek başına gelmez. Atıflar, yanıtın hangi kaynak bölümüne dayandığını görmenizi sağlar ve kontrolü kolaylaştırır. Ancak model, belgedeki bir ifadeyi doğru alıntılasa bile onu yanlış bağlamda kullanabilir.
Bu yüzden yalnızca atıf olup olmadığına bakmayın. Alıntılanan bölümün, yanıtta öne sürülen bilgiyi gerçekten destekleyip desteklemediğini de kontrol edin.