AI Destekli Yazılım Geliştirmede Yapılandırılmış Çıktı Sözleşmesi

AI destekli yazılım geliştirmede JSON Schema ile sınır çizmek

Generative AI kullanan bir kod akışında asıl risk modelin geçersiz JSON üretmesi değildir; geçerli fakat operasyonel olarak yanlış bir karar üretmesidir. Örneğin bir bağımlılık güncelleme ajanının paket adını, değişiklik türünü ve gerekçeyi serbest metinden ayıklamak yerine yanıtı baştan şemaya zorlayın. Bu yaklaşım, downstream tarafta regex ile ayrıştırma yapılmasını engeller ve iş kurallarını LLM promptundan uygulama koduna taşır.

import { z } from 'zod';

export const ChangePlan = z.object({
  packageName: z.string().regex(/^[a-z0-9@/_-]+$/i),
  changeType: z.enum(['patch', 'minor', 'major']),
  targetVersion: z.string().regex(/^\d+\.\d+\.\d+([-.+][0-9A-Za-z.-]+)?$/),
  breakingChanges: z.array(z.string()).max(10),
  requiresHumanApproval: z.boolean()
}).strict();

export type ChangePlan = z.infer<typeof ChangePlan>;

export function validateModelOutput(raw: unknown): ChangePlan {
  return ChangePlan.parse(raw);
}

İncelik: .strict() eklenmezse modelin eklediği confidence, analysis veya ileride araç çağrısına yanlışlıkla aktarılabilecek başka alanlar sessizce kabul edilir. Şema doğrulamasından sonra ayrıca alanlar arası kuralları denetleyin: changeType === 'major' iken requiresHumanApproval değeri false ise yanıtı reddetmek, JSON Schema'nın tek başına ifade etmekte zorlandığı bir domain invariant'ıdır. Bu ayrım, bir yapay zeka kursu veya llm eğitimi laboratuvarında mutlaka uygulanmalıdır.

LLM eğitimi için sözleşme testleri ve semantik doğrulama

Bir LLM'i yalnızca örnek prompta verdiği güzel yanıtla değerlendirmeyin. Vitest veya pytest ile sürümlenmiş bir test seti oluşturun; her testte giriş, beklenen kabul-red kararı ve domain assertion bulunsun. Sıcaklık değeri sıfır olsa bile sağlayıcı tarafındaki model güncellemesi, tokenizer farkı veya araç tanımındaki alan sırası çıktıyı değiştirebilir. Bu nedenle tam metin golden test yerine şema, iş kuralı ve izin verilen eylem kümesini test edin.

import { describe, expect, it } from 'vitest';
import { validateModelOutput } from './change-plan.js';

describe('change plan contract', () => {
  it('major update requires approval', () => {
    const plan = validateModelOutput({
      packageName: 'express',
      changeType: 'major',
      targetVersion: '5.0.0',
      breakingChanges: ['router matching behavior changed'],
      requiresHumanApproval: true
    });

    expect(plan.requiresHumanApproval || plan.changeType !== 'major').toBe(true);
  });

  it('rejects prompt-injected extra action fields', () => {
    expect(() => validateModelOutput({
      packageName: 'lodash', changeType: 'patch', targetVersion: '4.17.22',
      breakingChanges: [], requiresHumanApproval: false,
      shellCommand: 'rm -rf /'
    })).toThrow();
  });
});

Test matrisine en az şu mutasyonları ekleyin: sürüm alanına doğal dil eklenmesi, enum yerine yakın anlamlı değer gelmesi, boş dizi yerine null gelmesi, ekstra araç parametresi ve birbiriyle çelişen alanlar. CI'da model çağrısı maliyetliyse kayıtlı fixture'larla her pull request'te sözleşme testini, gerçek modelle ise gece çalışan ayrı bir regresyon job'unu koşturun. Vibe coding eğitimi ve vibe coding kursu içeriklerinde sık görülen hata, modelin ilk demoda ürettiği nesneyi API sözleşmesi kabul etmektir; sözleşmenin sahibi model değil uygulamadır.

Yapılandırılmış çıktı gecikmesini OpenTelemetry ile ölçmek

Şema eklemenin gecikme ve token maliyetini tahmin etmeyin, span verisiyle ölçün. OpenTelemetry SDK ile her çağrıda model adı, giriş-çıkış token sayısı, yeniden deneme sayısı, şema doğrulama sonucu ve toplam süreyi kaydedin. Ardından serbest JSON ayrıştırmalı eski akış ile strict schema kullanan yeni akışı aynı 200-500 istekten oluşan sabit veri kümesinde karşılaştırın. Karşılaştırmada p50 yerine p95, hata oranı ve istek başına toplam tokenı birlikte raporlayın; şema promptu büyütürken parse-repair çağrılarını azaltabilir.

import { trace, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('llm-contract');

export async function generatePlan(input: string) {
  return tracer.startActiveSpan('llm.generate_plan', async (span) => {
    const started = performance.now();
    try {
      const response = await client.responses.create({
        model: process.env.LLM_MODEL,
        input,
        text: { format: { type: 'json_schema', name: 'change_plan', strict: true, schema } }
      });
      const plan = validateModelOutput(JSON.parse(response.output_text));
      span.setAttributes({
        'llm.contract.valid': true,
        'llm.latency_ms': performance.now() - started,
        'llm.output_tokens': response.usage?.output_tokens ?? 0
      });
      return plan;
    } catch (error) {
      span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });
      span.setAttribute('llm.contract.valid', false);
      throw error;
    } finally {
      span.end();
    }
  });
}

Jaeger veya Grafana Tempo'da llm.generate_plan span'larını sorgulayın; Prometheus için ayrıca llm_contract_validation_failures_total ve llm_request_duration_seconds histogramlarını yayınlayın. Örnek bir önce-sonra deneyi şöyle tasarlanır: önce serbest metin + en fazla iki repair çağrısı, sonra strict schema + tek çağrı; aynı corpus, aynı model ayarı, aynı concurrency. Beklenen mekanizma şudur: strict schema bazı yanıtlarda üretim süresini artırabilir, ancak başarısız parse sonrası yapılan ikinci ağ çağrısını kaldırıyorsa p95 düşer. Bu veri olmadan yapılan performans yorumu, özellikle ai destekli yazılım geliştirme ekiplerinde maliyet optimizasyonu değildir.

CI CD pipeline içinde şema değişikliğini dağıtımdan önce yakalamak

Şema bir uygulama arayüzüdür; bu yüzden API sürümü gibi ele alınmalıdır. Pull request aşamasında JSON Schema diff'i çıkarın, geriye dönük uyumsuz alan değişimlerini durdurun ve test fixture'larını çalıştırın. Aşağıdaki GitHub Actions adımı, şema değiştiğinde Vitest sözleşme testlerini çalıştırır. Gerçek ekiplerde buna ek olarak jsonschema-diff veya oasdiff ile required alan ekleme, enum daraltma ve tür değişimi gibi kırıcı değişiklikleri fail ettirmek gerekir.

name: llm-contract
on:
  pull_request:
    paths:
      - 'schemas/**'
      - 'src/change-plan.ts'
      - 'tests/contracts/**'
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
      - run: npm ci
      - run: npx vitest run tests/contracts
      - run: npx ajv compile -s schemas/change-plan.json

Container imajında şema ve uygulama kodunu aynı immutable digest ile yayınlayın. Docker eğitimi kapsamında pratik bir doğrulama, imajın içine fixture koymak değil, CI'da o imajı çalıştırıp harici fixture mount etmektir: docker run --rm -v "$PWD/tests:/tests:ro" app-image npm run test:contract. Bu sayede derleme aşamasındaki dosya ile yayınlanan runtime imajı arasındaki fark yakalanır. Devops eğitimi programlarında bu kontrolü deployment sonrasına bırakmak yaygın bir hatadır; kırıcı şema değişimi bir canary pod'a ulaşmadan önce CI'da durmalıdır.

Cloud native mimari üzerinde şema uyumluluğu ve geri alma

Bir cloud native mimari içinde farklı servisler aynı LLM çıktısını tüketiyorsa, container orchestration katmanında producer ve consumer sürümlerinin kısa süre birlikte yaşamasını planlayın. Kubernetes deployment'ında önce yeni consumer sürümünü, sonra yeni producer şemasını yayınlamak çoğu zaman daha güvenlidir. Yeni alanı önce opsiyonel ekleyin, eski consumer kaldırıldıktan sonraki ayrı sürümde required yapın. Bu iki aşamalı genişlet-sonra-sıkılaştır yaklaşımı, rolling update sırasında eski pod'un yeni payload almasıyla oluşan hata dalgasını engeller.

Kubernetes eğitimi veya minikube ile yapılan yerel laboratuvarda iki consumer sürümünü kasıtlı olarak aynı anda çalıştırın: kubectl scale deployment/consumer-v1 --replicas=1 ve kubectl scale deployment/consumer-v2 --replicas=1. Ardından producer'ın yeni alanı gönderdiği senaryoda her iki sürümün hata sayısını kubectl logs -l app=consumer --prefix ile doğrulayın. Bu test, yalnızca tek pod ile çalışan geliştirme ortamının gizlediği sürüm geçişi problemini görünür yapar.

Altyapı tarafında terraform ve infrastructure as code kullanıyorsanız şema sürümünü deployment değişkeni olarak izleyin. Örneğin AWS eğitimi laboratuvarında bir ECS task definition environment alanı, Google Cloud eğitimi laboratuvarında ise Cloud Run revision environment alanı üzerinden CONTRACT_VERSION=2 geçilebilir. terraform plan -detailed-exitcode sonucunu CI'da saklayın; plan ile apply arasındaki sürüm drift'ini incelemeden şema rollout'u yapmayın. Geri alma sırasında yalnızca container tag'ini değil, kabul edilen şema sürümü matrisini de eski hale getirmek gerekir.

Yazılım eğitimi için üretime yakın laboratuvar sırası

Teknoloji eğitimi tasarlarken katılımcının sadece prompt yazmasını değil, bir çıktının yaşam döngüsünü işletmesini hedefleyin. İlk laboratuvarda Zod veya Pydantic ile şema kurulsun; ikinci laboratuvarda Ajv ile negatif fixture testleri yazılsın; üçüncü laboratuvarda OpenTelemetry Collector ve Jaeger ile p95 karşılaştırması yapılsın; son laboratuvarda CI CD pipeline üzerinden container dağıtımı yapılsın. Bu sıra, yapay zeka eğitimi içeriğini model kullanımından sistem mühendisliğine taşır.

Yerel başlangıç için aşağıdaki komutlarla OpenTelemetry Collector ve Jaeger ayağa kaldırılabilir; uygulamanın OTLP endpoint'i bu collector servisine yönlendirilir. Böylece llm eğitimi sırasında katılımcı, yalnızca yanıt kalitesini değil çağrı zincirini de inceler.

docker network create observability
docker run -d --name jaeger --network observability   -p 16686:16686 -p 4317:4317   jaegertracing/all-in-one
docker run --rm --network observability   -e OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317   app-image npm run benchmark:contracts

Bu laboratuvarın teslim kriteri somuttur: katılımcı 50 adet adversarial fixture'ın tamamında beklenen kabul-red sonucunu üretmeli, trace ekranında validation hatasını ayrı span olarak gösterebilmeli ve schema değişikliği yapan bir pull request'i CI'da kırıcı değişiklik nedeniyle başarısız kılmalıdır. Yapay zeka kursu seçerken veya kurum içi eğitim hazırlarken bu tür doğrulanabilir artefaktlar yoksa, eğitim genellikle üretim entegrasyonunun en zor kısmını atlıyordur.

Sık Sorulan Sorular

AI destekli yazılım geliştirmede JSON Schema tek başına güvenli mi?

Hayır. JSON Schema tür, enum ve alan yapısını denetler; ancak domain kuralını denetlemez. Şema doğrulamasından sonra Zod refine, Pydantic model_validator veya ayrı bir policy fonksiyonuyla major değişiklikte insan onayı gibi alanlar arası kuralları uygulayın. Ayrıca strict modla tanımsız alanları reddedin.

LLM eğitimi sırasında yapılandırılmış çıktı gecikmesi nasıl ölçülür?

OpenTelemetry ile çağrı süresi, input-output tokenları, retry sayısı ve validation sonucunu span attribute olarak kaydedin. Aynı fixture corpus üzerinde serbest çıktı + repair akışı ile strict schema akışını çalıştırın; p50, p95, parse hata oranı ve istek başına toplam tokenı karşılaştırın. Jaeger veya Grafana Tempo'da yalnızca başarılı çağrıları değil hata span'larını da sorgulayın.

Kubernetes eğitimi için LLM şema değişikliği minikube ortamında nasıl test edilir?

Minikube üzerinde eski ve yeni consumer deployment'larını aynı anda birer replica ile çalıştırın. Producer'ın yeni payload'ını iki consumer'a gönderin, HTTP 4xx-5xx sayaçlarını ve pod loglarını toplayın. Önce consumer'ın yeni alanı tolere eden sürümünü, sonra producer'ı yayınlayarak genişlet-sonra-sıkılaştır geçişini doğrulayın.

Terraform ile infrastructure as code kullanırken LLM sözleşme sürümü nasıl yönetilir?

Sözleşme sürümünü ECS task definition, Kubernetes ConfigMap veya Cloud Run environment variable olarak Terraform ile tanımlayın. CI'da terraform plan -detailed-exitcode çalıştırın ve uygulama imajı digest'i ile CONTRACT_VERSION değerini aynı release kaydında tutun. Geri alma prosedürü hem imaj digest'ini hem sözleşme uyumluluk değerini geri çevirmelidir.