8.3 Scorers Bawaan

Tujuan bab

Setelah bab ini kamu bisa:

• Menjelaskan apa itu scorer dan kenapa keluarannya berupa skor, bukan lulus/gagal
• Memilih scorer bawaan yang tepat dari keempat kategorinya
• Memasang live evaluation pada agent dan langkah workflow
• Mengatur sampling dan menjelaskan kenapa keputusannya deterministik
• Memakai Quick Checks untuk pemeriksaan cepat tanpa memanggil LLM

Prasyarat

• 8.2 Logging & Metrics
• Paket @mastra/evals terpasang: npm install @mastra/evals@latest

Kenapa skor, bukan lulus atau gagal

Tes perangkat lunak biasa punya kondisi lulus/gagal yang jelas. Keluaran AI tidak — masukan yang sama bisa menghasilkan keluaran yang berbeda.

Scorer menjembatani jarak itu. Ia tes otomatis yang menilai keluaran agent lewat metode yang dinilai model, berbasis aturan, atau statistik, dan mengembalikan skor: nilai numerik yang biasanya antara 0 dan 1.

Angka itu memungkinkan tiga hal yang tidak bisa dilakukan penilaian lulus/gagal:

• Melacak performa dari waktu ke waktu
• Membandingkan dua pendekatan secara objektif
• Menemukan area yang perlu diperbaiki, bukan sekadar tahu ada yang salah

Empat kategori scorer bawaan

Akurasi dan keandalan

Menilai seberapa benar, jujur, dan lengkap jawaban agent.

Scorer	Menilai	Arah baik
answer-relevancy	Seberapa baik jawaban menjawab pertanyaan	Makin tinggi
answer-similarity	Perbandingan dengan jawaban acuan, untuk CI/CD	Makin tinggi
faithfulness	Seberapa akurat jawaban mewakili konteks yang diberikan	Makin tinggi
hallucination	Kontradiksi faktual dan klaim tak berdasar	Makin rendah
completeness	Apakah jawaban memuat semua informasi yang perlu	Makin tinggi
content-similarity	Kemiripan tekstual tingkat karakter	Makin tinggi
textual-difference	Perbedaan tekstual antar string	Makin tinggi = makin mirip
tool-call-accuracy	Apakah LLM memilih tool yang benar	Makin tinggi
trajectory-accuracy	Urutan tindakan yang diharapkan lintas span	Makin tinggi
prompt-alignment	Kesesuaian jawaban dengan maksud, kelengkapan, dan format prompt	Makin tinggi
multi-turn-judge	Menilai tiap giliran percakapan terhadap kriteria bahasa biasa	0 atau 1

Perhatikan arah skornya

hallucination dan toxicity adalah dua scorer yang makin rendah makin baik — kebalikan dari kebanyakan yang lain. Menetapkan ambang batas > 0.8 untuk hallucination berarti kamu meloloskan jawaban yang paling banyak mengarang.

Mutu konteks

Menilai kualitas dan relevansi konteks yang dipakai saat menghasilkan jawaban — relevan langsung untuk RAG di Bagian 5.

Scorer	Menilai
context-precision	Peringkat konteks memakai Mean Average Precision — konteks relevan yang muncul lebih awal mendapat skor lebih tinggi
context-relevance	Kegunaan konteks lewat tingkat relevansi dan pelacakan pemakaian, sekaligus mendeteksi konteks yang hilang

Dokumentasi memberi panduan memilih yang jelas:

• Context Precision saat urutan konteks penting dan kamu butuh metrik information retrieval standar — ideal untuk mengevaluasi peringkat RAG
• Context Relevance saat kamu butuh penilaian relevansi yang rinci, ingin melacak pemakaian konteks, dan mengidentifikasi celah

Keduanya mendukung konteks statis maupun ekstraksi konteks dinamis — mengambil konteks dari run lewat fungsi kustom, yang cocok untuk sistem RAG dan basis data vektor.

Mutu keluaran

Menilai kepatuhan pada format, gaya, dan keamanan.

Scorer	Menilai	Arah baik
tone-consistency	Konsistensi formalitas, kompleksitas, dan gaya	Makin tinggi
toxicity	Konten berbahaya atau tidak pantas	Makin rendah
bias	Potensi bias dalam keluaran	Makin rendah
keyword-coverage	Pemakaian terminologi teknis	Makin tinggi

Quick Checks — tanpa LLM sama sekali

Ini kategori yang paling sering terlupakan dan paling murah. Quick Checks adalah micro-scorer tanpa LLM untuk asersi cepat dan deterministik.

Check	Skor 1 bila
checks.includes	Keluaran memuat substring tertentu
checks.excludes	Keluaran tidak memuat substring tertentu
checks.equals	Keluaran persis sama dengan string tertentu
checks.matches	Keluaran cocok dengan regex
checks.similarity	Kemiripan string lewat koefisien Dice (0-1, atau biner dengan ambang)
checks.calledTool	Sebuah tool dipanggil minimal N kali
checks.didNotCall	Sebuah tool tidak dipanggil
checks.toolOrder	Tool dipanggil dalam urutan tertentu
checks.maxToolCalls	Jumlah pemanggilan tool masih dalam batas
checks.usedNoTools	Tidak ada tool yang dipanggil
checks.noToolErrors	Tidak ada pemanggilan tool yang error

Mulai dari Quick Checks

Scorer berbasis LLM memerlukan panggilan model — lambat dan berbiaya. Sebelum memakainya, tanyakan apakah yang kamu uji sebenarnya deterministik.

"Apakah agent memanggil tool pencarian sebelum menjawab?" tidak butuh model untuk menilainya — checks.calledTool menjawabnya dengan pasti, instan, dan gratis. Simpan scorer LLM untuk pertanyaan yang benar-benar butuh penilaian, seperti "apakah jawabannya relevan?".

Live evaluation pada agent

Live evaluation menilai keluaran secara real-time saat agent berjalan, bukan dalam batch terpisah.

// src/mastra/agents/evaluated-agent.ts
import { Agent } from '@mastra/core/agent'
import {
  createAnswerRelevancyScorer,
  createToxicityScorer,
} from '@mastra/evals/scorers/prebuilt'

export const evaluatedAgent = new Agent({
  id: 'evaluated-agent',
  name: 'Evaluated Agent',
  instructions: 'Bantu pengguna dengan pertanyaan mereka.',
  model: 'openai/gpt-5.6-sol',
  scorers: {
    relevancy: {
      scorer: createAnswerRelevancyScorer({ model: 'openai/gpt-5-mini' }),
      sampling: { type: 'ratio', rate: 0.5 },
    },
    safety: {
      scorer: createToxicityScorer({ model: 'openai/gpt-5-mini' }),
      sampling: { type: 'ratio', rate: 1 },
    },
  },
})

Perhatikan tiga hal.

Scorer diimpor dari @mastra/evals/scorers/prebuilt, dan namanya mengikuti pola create<Nama>Scorer.

Tiap scorer memakai model sendiri — di sini model ringan, karena penilai tidak perlu sekuat agent yang dinilai.

Rate berbeda per scorer. Keamanan diperiksa pada semua keluaran (rate: 1), sementara relevansi cukup pada separuhnya. Ini pola yang masuk akal: pelanggaran keamanan tidak boleh lolos, penurunan relevansi cukup terdeteksi secara statistik.

Cara live evaluation bekerja

Eksekusinya asinkron. Live evaluation berjalan di latar belakang tanpa memblokir respons agent. Sistem AI-mu tetap responsif sementara penilaian berlangsung.

Sampling dikendalikan lewat rate (0 sampai 1):

Rate	Artinya
1.0	Nilai setiap respons (100%)
0.5	Nilai separuh respons
0.1	Nilai 10% respons
0.0	Matikan penilaian

Sampling-nya deterministik, bukan acak

Ini detail penting yang mudah terlewat, dan konsekuensinya besar.

Dokumentasi menyebut bahwa keputusan sampling diturunkan dari trace ID, bukan diundi secara acak. Dua akibat praktisnya:

• Scorer dengan rate yang sama menilai trace yang sama, sehingga skornya bisa dibandingkan secara adil pada lalu lintas yang sama
• Menjalankan ulang trace yang sama menghasilkan keputusan sampling yang sama, sehingga cakupan sampelnya bisa direproduksi

Kalau sampling-nya acak, dua scorer pada rate 0.5 akan menilai dua himpunan trace yang berbeda — dan membandingkan skor keduanya menjadi tidak bermakna.

Live evaluation pada langkah workflow

Scorer juga bisa dipasang pada langkah workflow. Tiap scorer menerima masukan dan keluaran langkah itu sendiri, sehingga kamu bisa mengukur mutu di tiap tahap alih-alih hanya jawaban akhir.

// src/mastra/workflows/content-workflow.ts
import { createWorkflow, createStep } from '@mastra/core/workflows'
import { z } from 'zod'
import { customStepScorer } from '../scorers/custom-step-scorer.ts'

const contentStep = createStep({
  id: 'content-step',
  inputSchema: z.object({ topic: z.string() }),
  outputSchema: z.object({ content: z.string() }),
  scorers: {
    customStepScorer: {
      scorer: customStepScorer(),
      sampling: {
        type: 'ratio',
        rate: 1,
      },
    },
  },
  execute: async ({ inputData }) => {
    return { content: await generateContent(inputData.topic) }
  },
})

export const contentWorkflow = createWorkflow({
  id: 'content-workflow',
  inputSchema: z.object({ topic: z.string() }),
  outputSchema: z.object({ content: z.string() }),
})
  .then(contentStep)
  .commit()

Kemampuan ini menjawab pertanyaan yang tidak bisa dijawab dengan menilai keluaran akhir: langkah mana yang menurunkan mutu? Workflow lima langkah yang hasil akhirnya buruk bisa disebabkan langkah kedua — dan tanpa skor per langkah, kamu hanya bisa menebak.

Memilih scorer untuk kasusmu

Kesalahan umum

Gejala: Ambang batas mutu ditetapkan, tapi jawaban yang jelas buruk tetap lolos — bahkan mendapat skor tinggi. Penyebab: Salah membaca arah skor. hallucination dan toxicity memakai konvensi makin rendah makin baik, kebalikan dari kebanyakan scorer lain. Perbaikan: Periksa arah tiap scorer sebelum menetapkan ambang. Untuk kedua scorer itu, ambangnya berbentuk "harus di bawah", bukan "harus di atas".

Gejala: Biaya evaluasi hampir menyamai biaya menjalankan agent itu sendiri. Penyebab: Semua scorer memakai LLM pada rate: 1, termasuk untuk hal-hal yang sebenarnya deterministik. Perbaikan: Pindahkan pemeriksaan deterministik ke Quick Checks, yang tidak memanggil model sama sekali. Turunkan rate untuk scorer LLM yang bersifat pemantauan, dan simpan rate: 1 hanya untuk yang menyangkut keamanan.

Coba sendiri

Tantangan: Pasang live evaluation berlapis pada agent RAG dari 5.3, dan buktikan bahwa skornya menangkap penurunan mutu yang kamu buat sendiri.

Ketentuan:

1. Pasang minimal satu scorer dari tiap kategori: satu Quick Check, satu akurasi, satu mutu konteks, dan satu mutu keluaran
2. Quick Check-nya harus memeriksa sesuatu yang benar-benar deterministik — misalnya bahwa tool pencarian dipanggil sebelum menjawab
3. Beri rate: 1 untuk scorer keamanan, dan rate lebih rendah untuk yang bersifat pemantauan. Catat alasan tiap angka
4. Jalankan 20 pertanyaan dan periksa skornya di Studio
5. Turunkan mutu dengan sengaja: ubah topK menjadi 1, dan longgarkan instruksi agent sehingga ia boleh menjawab dari pengetahuan umum
6. Jalankan 20 pertanyaan yang sama, dan bandingkan skornya
7. Identifikasi scorer mana yang paling tajam menangkap penurunan itu

Checklist penerimaan:

• [ ] Keempat kategori terwakili, dan Quick Check-nya tidak memanggil model
• [ ] Skor sebelum dan sesudah langkah 5 berbeda secara terlihat — kamu punya angkanya, bukan kesan
• [ ] Kamu bisa menyebutkan scorer mana yang paling sensitif terhadap perubahan topK, dan menjelaskan kenapa
• [ ] Kamu bisa menyebutkan scorer mana yang paling sensitif terhadap perubahan instruksi
• [ ] Tidak ada scorer yang ambangnya salah arah
• [ ] Kamu bisa menjelaskan kenapa sampling deterministik penting untuk membandingkan kedua putaran ini

Petunjuk: Checklist terakhir adalah kunci validitas percobaan ini. Karena sampling diturunkan dari trace ID dan bukan diundi, dua scorer pada rate yang sama menilai trace yang sama — sehingga perbandingan antar scorer bermakna. Kalau sampling-nya acak, perbedaan skor yang kamu lihat bisa saja berasal dari himpunan sampel yang kebetulan berbeda, bukan dari perubahan yang kamu buat.

Ikhtisar

• Scorer mengembalikan skor 0-1, bukan lulus/gagal — karena keluaran AI non-deterministik. Skor memungkinkan pelacakan, perbandingan, dan identifikasi celah.
• Empat kategori: akurasi & keandalan, mutu konteks, mutu keluaran, dan Quick Checks.
• hallucination, toxicity, dan bias makin rendah makin baik — kebalikan dari kebanyakan scorer lain.
• Quick Checks tidak memanggil LLM sama sekali. Pakai untuk apa pun yang deterministik sebelum menjangkau scorer berbasis model.
• Untuk RAG: context-precision saat urutan penting, context-relevance saat butuh penilaian rinci dan deteksi celah.
• Live evaluation berjalan asinkron dan tidak memblokir respons agent.
• Sampling deterministik berdasarkan trace ID, bukan acak — sehingga skor antar scorer bisa dibandingkan dan cakupan sampel bisa direproduksi.
• Scorer bisa dipasang per langkah workflow, menjawab pertanyaan "langkah mana yang menurunkan mutu?".

Lanjut ke mana

Scorer bawaan mencakup banyak hal, tapi tidak kriteria yang khas untuk domainmu. Bab terakhir bagian ini tentang menulis scorer sendiri dan menjalankannya sebagai gerbang mutu: 8.4 Custom Scorer & CI.