Bir LLM'den yapılandırılmış veri almak
İşe yarayan LLM işlerinin çoğu aslında sohbet değil. Modele bir fatura, bir sözleşme ya da bir e-posta veriyorsunuz ve karşılığında alanlar istiyorsunuz: bir sayı, bir tarih, bir satır listesi; kodunuzun saklayabileceği ve toplayabileceği bir şey. Model dağınık dokümanları okumakta iyi. Bir programın güvenebileceği bir çıktı vermekte ise varsayılan olarak iyi değil.
Extraction kodunun çoğu tam bu iki şeyin arasındaki boşlukta bozuluyor. Bu yazıda o boşluğu C# ile, örnek olarak bir fatura üzerinden kapatıyorum: bir şekil iste, gelen cevabı bir yabancı göndermiş gibi kontrol et, gerekçesiyle tekrar dene ve ne zaman durup bir insana sorman gerektiğini bil.
JSON istemenin üç yolu
En zayıf yol prompt'a "JSON olarak cevap ver" yazmak. Çoğu zaman JSON geliyor. Bazen Markdown code fence
içine sarılmış JSON geliyor, bazen arkasına eklenmiş nazik bir cümleyle, bazen de invoiceNumber beklediğiniz
yerde invoice_no diye bir alanla. Bunların her biri, elli dokümanda bir ortaya çıkan bir parsing bug'ı.
Bir üst basamak JSON mode: sağlayıcı çıktının geçerli JSON olacağını garanti ediyor. Fence'leri ve sondaki cümleleri bu çözüyor. Şekil hakkında ise hiçbir şey söylemiyor: alanlarınızın yarısı eksik olan bir obje de dahil, geçerli her JSON objesi geçiyor.
En güçlüsü structured output modu: isteğin yanında bir JSON Schema gönderiyorsunuz ve sağlayıcı üretimi o şemaya göre kısıtlıyor. Her sağlayıcı ya da model bunu desteklemiyor; destekleyenler de JSON Schema'nın her keyword'ünü desteklemiyor. Çalıştığı yerde şekil sorusunu kapatıyor: property adları, tipler ve zorunlu alanlar istendiği gibi geliyor.
Üçünün de çözmediği şey, değerlerin doğru olup olmadığı. Bir şema total'ın bir sayı olduğunu söyleyebilir.
O sayının faturada yazan sayı olduğunu söyleyemez.
Şema bir C# tipinden geliyor
JSON Schema'yı elle yazmıyorum. Sonunda elde etmek istediğim tip şekli zaten tarif ediyor; şemayı kütüphanenin ondan türetmesine izin veriyorum:
using System.ComponentModel;
public sealed record InvoiceLine(
string Description,
[property: Description("Quantity as printed. Greater than zero.")] decimal Quantity,
[property: Description("Price per unit, before tax.")] decimal UnitPrice,
[property: Description("Line amount as printed on the invoice.")] decimal LineTotal);
[Description("An invoice, using only values printed on the document.")]
public sealed record Invoice(
[property: Description("Invoice number exactly as printed.")] string InvoiceNumber,
DateOnly IssueDate,
[property: Description("ISO 4217 code, e.g. EUR.")] string Currency,
IReadOnlyList<InvoiceLine> Lines,
decimal Subtotal,
decimal Tax,
decimal Total,
[property: Description("Purchase order number, or null if none is printed.")] string? PurchaseOrder);
Microsoft.Extensions.AI'daki AIJsonUtilities.CreateJsonSchema(typeof(Invoice)) bunu bir şemaya çeviriyor.
[Description] attribute'ları description keyword'lerine, DateOnly "format": "date" olan bir string'e,
nullable PurchaseOrder da ["string", "null"]'a dönüşüyor. Şemayı bir kez ekrana basıp okuyun. Model tam
olarak buna göre tutulacak ve açıklamasını yazmayı unuttuğunuz bir property'yi yakalamanın en hızlı yolu bu.
Nullable alan göründüğünden daha önemli. Bir RAG modeline "bilmiyorum" deme izni vermenin extraction'daki karşılığı bu: bir alan null olamıyorsa, onu bulamayan model yine de bir şey üretiyor. Opsiyonel alanları opsiyonel yapın ve açıklamada null'ın ne anlama geldiğini yazın.
GetResponseAsync<T> ile istemek
Microsoft.Extensions.AI'da IChatClient üzerinde tesisatı halleden generic bir GetResponseAsync<T> var.
Şemayı T'den oluşturuyor, response format olarak gönderiyor ve cevabı deserialize edebilen bir
ChatResponse<T> döndürüyor:
using System.Text.Json;
using Microsoft.Extensions.AI;
JsonSerializerOptions json = new(AIJsonUtilities.DefaultOptions)
{
RespectNullableAnnotations = true,
RespectRequiredConstructorParameters = true,
};
ChatResponse<Invoice> response =
await chat.GetResponseAsync<Invoice>(messages, json, cancellationToken: ct);
if (response.TryGetResult(out Invoice? invoice))
{
// invoice doğru şekilde. Doğru olup olmadığı bir sonraki bölümün konusu.
}
İki Respect ayarı yazdığınız satırlara değer. System.Text.Json varsayılan olarak hoşgörülü: eksik bir property
varsayılan değeri alıyor, bir null da non-nullable bir string'e gönül rahatlığıyla yerleşiyor. Bu ayarlarla
eksik bir invoiceNumber ya da tipin izin vermediği yerdeki bir null, kodunuza null veya 0 olarak
ulaşmak yerine deserialization'da hata veriyor.
Result yerine TryGetResult kullanın. Dokümantasyon, modellerin şemaya uymasının garanti olmadığını açıkça
söylüyor ve metin parse edilemediğinde Result exception fırlatıyor. Oraya varmanın olağan yolu token limitinde
kesilmiş bir cevap: response.FinishReason'da ChatFinishReason.Length var mı bakın; aynı isteği tekrar
denemek yerine limiti yükseltin.
Modelinizin native şema desteği yoksa useJsonSchemaResponseFormat: false geçin. Kütüphane bu durumda düz
JSON istiyor ve şemayı bir mesajın içine koyuyor; daha zayıf ama prompt'taki bir cümleden yine de iyi.
Sonuç güvenilmeyen bir girdi
Parse edildikten sonra faturaya internetten gelen bir request body'ye davrandığınız gibi davranın. Model dokümanı okudu, ama bir rakamı yanlış okumuş, iki kolonu karıştırmış ya da bir boşluğu makul görünen bir şeyle doldurmuş olabilir. Faturalar burada bize iyi davranıyor, çünkü kendi sağlamalarını taşıyorlar: satırlar çarpılınca tutuyor, satırların toplamı ara toplamı veriyor, ara toplam artı vergi genel toplamı veriyor.
Kontrolleri iki ayrı method olarak yazıyorum; sebebini bir sonraki bölüm anlatıyor:
static List<string> Validate(Invoice invoice)
{
List<string> errors = [];
if (invoice.Currency.Length != 3 || !invoice.Currency.All(char.IsAsciiLetterUpper))
errors.Add($"currency '{invoice.Currency}' is not a three-letter ISO 4217 code.");
if (invoice.IssueDate > DateOnly.FromDateTime(DateTime.UtcNow))
errors.Add($"issueDate {invoice.IssueDate:yyyy-MM-dd} is in the future.");
if (invoice.Lines.Count == 0)
errors.Add("lines is empty.");
for (int i = 0; i < invoice.Lines.Count; i++)
if (invoice.Lines[i].Quantity <= 0)
errors.Add($"lines[{i}].quantity is {invoice.Lines[i].Quantity}; it must be greater than zero.");
return errors;
}
static List<string> CheckArithmetic(Invoice invoice)
{
List<string> errors = [];
foreach (InvoiceLine line in invoice.Lines)
if (Math.Abs(line.Quantity * line.UnitPrice - line.LineTotal) > 0.01m)
errors.Add($"'{line.Description}': {line.Quantity} x {line.UnitPrice} is not {line.LineTotal}.");
decimal sum = invoice.Lines.Sum(l => l.LineTotal);
if (sum != invoice.Subtotal)
errors.Add($"the line totals add up to {sum}, but subtotal is {invoice.Subtotal}.");
if (invoice.Subtotal + invoice.Tax != invoice.Total)
errors.Add($"subtotal + tax is {invoice.Subtotal + invoice.Tax}, but total is {invoice.Total}.");
return errors;
}
Para decimal'dır, asla double değil. Satır kontrolü bir kuruşluk yuvarlamaya izin veriyor, çünkü birim
fiyatlar çoğu zaman satır tutarlarından daha fazla hassasiyetle yazılıyor; toplamlar izin vermiyor, çünkü
yazılı tutarları toplamak tam sonuç vermeli. Her mesaj alanı ve iki değeri de söylüyor, çünkü bu string'lerin
ikinci bir okuyucusu var.
İkisi birlikte faturanın kendi içinde tutarlı olduğunu kanıtlıyor. Kağıttakiyle aynı olduğunu kanıtlamıyor. Bir satırda ve ara toplamda 18.00'ı 13.00 okuyan bir model yukarıdaki her kontrolden geçer. Son bölümün var olma sebebi bu boşluk.
Neyin yanlış olduğunu söyleyen sınırlı bir retry
Doğrulama başarısız olduğunda aynı prompt'la tekrar sormak yazı tura atmak gibi. Hatalarla birlikte tekrar sormak ise bir düzeltme: model kendi cevabını ve tam olarak neyin tutmadığının listesini görüyor.
Ama her hata modele geri gitmemeli. "Satır toplamları 20.00 ediyor ama ara toplam 25.00" modelin bir şeyi yanlış okuduğu anlamına gelebilir, faturanın kendisinin yanlış olduğu anlamına da; tedarikçiler toplamı tutmayan faturalar gönderiyor. Bir modele uyuşmazlığı söylerseniz sayıları tutarlı hale getirir, hangisini değiştirmesi en kolaysa onu değiştirerek. Elinizde hiç kesilmemiş bir faturanın tertemiz bir kaydı kalır.
O yüzden döngünün içinde yalnızca Validate çalışıyor. Bunlar modelin sebep olduğu ve düzeltebileceği
hatalar: bozuk bir para birimi, atlanmış bir satır, uydurduğu bir tarih.
for (int attempt = 1; attempt <= 3; attempt++)
{
ChatResponse<Invoice> response =
await chat.GetResponseAsync<Invoice>(messages, json, cancellationToken: ct);
errors = response.TryGetResult(out Invoice? invoice)
? Validate(invoice)
: ["The response did not match the schema."];
if (errors.Count == 0)
return (invoice, errors);
messages.AddMessages(response);
messages.Add(new(ChatRole.User,
"The result failed these checks:\n- " + string.Join("\n- ", errors) +
"\nRe-read the document and correct only what is wrong."));
}
return (null, errors); // hatalarla birlikte bir insana gidiyor
AddMessages modelin cevabını konuşmaya ekliyor; böylece takip mesajı modelin görebildiği bir şeye atıf
yapıyor. Döngü sınırlı, çünkü her deneme tam bir istek tutuyor ve aynı kontrollerde iki kez kalan bir modelin
beşinci denemede geçmesi pek olası değil. Üç makul bir varsayılan; değiştirmeden önce kendi dokümanlarınızda
ölçün.
CheckArithmetic döngünün döndürdüğü fatura üzerinde bir kez çalışıyor. Bir şey raporlarsa fatura, kağıda
bakabilecek bir insana gidiyor. Model bakamaz ve ondan tahmin etmesi istenmemeli.
Bir insan ne zaman bakmalı?
Bazı kayıtlar her kontrolden geçse bile bir insana ulaşmalı. Sürecinizin önemsediği bir tutarın üzerindeki bir toplam. Daha önce hiç görmediğiniz bir tedarikçi. Normalde ödeme yapmadığınız bir para birimi. Bunlar extraction kuralı değil, iş kuralı; doğrulamadan sonra sıradan kodda yer alıyorlar.
Modele ne kadar emin olduğunu sormuyorum. Kendi bildirdiği bir güven puanı, arkasında kontrol edebileceğiniz hiçbir şey olmayan, üretilmiş bir değer daha. Başarısız bir kontrol kanıttır; bir "0.92" değildir.
Onun yerine örneklem alıyorum. Her şeyden geçmiş birkaç extraction'ı alıp kaynak dokümanlarla elle karşılaştırıyorum. Aritmetiği bozmayan yanlış okunmuş rakamı bulmanın tek yolu bu; ayrıca insan kuyruğunun fazla dolu mu, fazla boş mu olduğunu da söylüyor.
Bunların hiçbiri faturalara özgü değil. Sağlayıcının zorlayabileceği bir şekil isteyin, sıkı deserialize edin, şemanın ifade edemediğini kontrol edin, sınırlı sayıda gerekçeli retry yapın, gerisini kaynağa bakabilecek birine verin. Okumayı model yapıyor; neye inanılacağına kodunuz karar veriyor.
