मूल्यांकन (Evals)

blume eval आपके डॉक्स को एक टेस्ट सूट देता है — एक AI एजेंट केवल दस्तावेज़ों का उपयोग करके आपके उपयोगकर्ताओं के प्रश्नों के उत्तर देता है, एक जज उन उत्तरों को अंक देता है, और जब डॉक्स उत्तर नहीं दे पाते तो CI विफल हो जाता है।

blume audit आपको बताता है कि क्रॉलर आपके डॉक्स ढूँढ़ सकते हैं या नहीं। blume eval आपको बताता है कि क्या कोई वास्तव में उनका उपयोग कर सकता है: एक AI एजेंट आपके दस्तावेज़ों को उसी तरह पढ़ता है जैसे कोई अनजान व्यक्ति पढ़ेगा और उनसे उपयोगकर्ताओं के असली प्रश्नों के उत्तर देने की कोशिश करता है। जब डॉक्स में उत्तर नहीं लिखा होता, तो रन विफल हो जाता है और उस पेज का नाम बताता है जिसमें वह उत्तर होना चाहिए।

blume eval

blume eval  3 question(s) · Claude Code

  ✔ install-node-version         pass  1.00  14.2s  $0.14
  ✖ deploy-vercel                fail  0.40  38.9s  $0.31
      missing: the adapter is auto-detected
  ⊘ search-providers             skipped

  fix: content/docs/deployment.mdx  Docs could not answer: "How do I deploy to Vercel?" — missing: the adapter is auto-detected

  2 passed · 1 failed · 1 skipped · 1m 42s · $0.45

यह कैसे काम करता है

हर प्रश्न दो एजेंट सत्रों से होकर गुज़रता है, और इसके लिए वही एजेंट CLI इस्तेमाल होता है जो आपके पास पहले से इंस्टॉल है — डिफ़ॉल्ट रूप से Claude Code, या --agent codex के साथ Codex। Blume कोई API की नहीं रखता और स्वयं किसी मॉडल को कॉल नहीं करता।

1. रीडर केवल और केवल आपके दस्तावेज़ों का उपयोग करके प्रश्न का उत्तर देता है। यह एक खाली डायरेक्टरी में चलता है, जिसमें उसके फ़ाइल, शेल और वेब टूल बंद कर दिए जाते हैं, और यह एक निजी MCP सर्वर से जुड़ा होता है जो आपके डॉक्स परोसता है — वही search_docs/get_page टूल जो एक असली एजेंट आपकी डिप्लॉय की गई साइट पर इस्तेमाल करता है। यह आपका रेपो नहीं पढ़ सकता, इसलिए यह डॉक्स को ठीक वैसे ही अनुभव करता है जैसे कोई नया उपयोगकर्ता: जो लिखा नहीं है, उसका अस्तित्व नहीं है।
2. जज उत्तर को आपके द्वारा सूचीबद्ध तथ्यों के आधार पर आँकता है, बिना किसी टूल के। भावार्थ में कहा गया उत्तर पास होता है; कोई तथ्य छूट जाए या उसका खंडन हो तो फेल — और “दस्तावेज़ों में यह नहीं लिखा है” भी फेल ही है।

MCP स्नैपशॉट सीधे आपके कंटेंट स्रोतों से बनाया जाता है, इसलिए पहले blume build चलाने की ज़रूरत नहीं है, और कहीं कुछ भी डिप्लॉय या अपलोड नहीं किया जाता।

ऐसा उत्तर जिसे डॉक्स समर्थन नहीं कर सकते, तब भी फेल होता है जब एजेंट का पूर्व ज्ञान संयोग से सही हो — यही तो मुद्दा है। आपके डॉक्स ही एकमात्र स्रोत हैं जो शिप होता है।

मूल्यांकन लिखना

प्रश्न प्रोजेक्ट रूट में evals.yaml में रहते हैं। आपके मौजूदा डॉक्स से एजेंट द्वारा एक शुरुआती फ़ाइल तैयार करवाने के लिए:

blume eval init

या इसे हाथ से लिखें:

questions:
  - id: install-node-version
    question: What is the minimum Node.js version required?
    expected:
      - Node 22.12 or newer
    routes: /docs/quickstart
  - id: deploy-vercel
    question: How do I deploy to Vercel?
    expected:
      - run blume build
      - the output directory is dist
    routes:
      - /docs/deployment
  - id: search-providers
    question: Which search providers are supported?
    expected:
      - pagefind is the default
    severity: warning # a miss warns instead of failing CI
    skip: true # temporarily excluded, reported as skipped

• expected उन तथ्यों को सूचीबद्ध करता है जो एक सही उत्तर में सारभूत रूप से मौजूद होने चाहिए — जज भावार्थ स्वीकार करता है और खंडन अस्वीकार करता है।
• routes उस पेज (या पेजों) का नाम बताता है जिसे प्रश्न का उत्तर देना चाहिए। तब रिपोर्ट में विफलता उस पेज की स्रोत फ़ाइल से जोड़ दी जाती है; और जो संकेत अब किसी पेज से मेल नहीं खाता, उसके बारे में चुपचाप अनदेखा करने के बजाय चेतावनी दी जाती है।
• severity: warning किसी प्रश्न को CI विफल किए बिना रिपोर्ट में बनाए रखता है; skip: true किसी प्रश्न को पूरी तरह बाहर बैठा देता है।

ऐसे प्रश्न लिखें जो आपके उपयोगकर्ता वास्तव में पूछते हैं — सपोर्ट थ्रेड्स, GitHub इश्यूज़ और ऑनबोर्डिंग कॉल्स वाले प्रश्न। सर्वोत्तम मूल्यांकन आपके डॉक्स द्वारा किए गए किसी वादे (“शून्य-कॉन्फ़िग डिप्लॉय”) को ऐसे प्रश्न के रूप में दर्ज करते हैं जो तब टूट जाता है जब कोई PR उस वादे को तोड़ता है।

CI को विफल करना

एग्ज़िट कोड ही अनुबंध है: कोई भी विफल प्रश्न ग़ैर-शून्य एग्ज़िट देता है। जब आप किसी बैकलॉग से बाहर निकल रहे हों, तो --threshold इस द्वार को एक पासिंग अंश तक ढीला कर देता है:

blume eval                    # every question must pass
blume eval --threshold 0.8    # at least 80% must pass
blume eval --json             # machine-readable report on stdout

JSON रिपोर्ट का वही diagnostics + summary आकार होता है जो blume validate --json और blume audit --json का है, साथ में प्रति-प्रश्न परिणाम (उत्तर, स्कोर, छूटे हुए तथ्य, लागत) भी होते हैं।

चूँकि हर प्रश्न दो मॉडल सत्र होता है, एक eval रन में असली पैसा और मिनट खर्च होते हैं — प्रति-प्रश्न खर्च चलते-चलते प्रिंट होता रहता है। एक समझदार CI सेटअप blume eval को हर पुश पर नहीं, बल्कि डॉक्स में बदलाव होने पर चलाता है।

निष्कर्षों को ठीक करना

हर विफलता छूटे हुए तथ्यों और उस पेज का नाम बताती है जिसे उन्हें बताना चाहिए। इसके बजाय पूरी रिपोर्ट एजेंट को सौंपने के लिए:

blume eval --fix

यह पूरी JSON रिपोर्ट एक फ़ाइल में लिखता है और एजेंट को एक ऐसे प्रॉम्प्ट के साथ इंटरैक्टिव रूप से खोलता है जो उसे हर विफल प्रश्न से होकर ले जाता है: नामित पेज पढ़ो, छूटे हुए तथ्यों को पेज की अपनी शैली में जोड़ो, और तब तक blume eval दोबारा चलाओ जब तक सब कुछ पास न हो जाए। यह सत्र जान-बूझकर इंटरैक्टिव है — आप एजेंट के अपने अनुमति-प्रवाह के ज़रिए संपादनों की समीक्षा करते हैं — और एजेंट को कह दिया जाता है कि ग्रीन तक पहुँचने के लिए वह कभी भी प्रश्न न हटाए और न ही अपेक्षित तथ्यों को कमज़ोर करे।

फ़्लैग्स

• --agent claude|codex — कौन-सा एजेंट CLI रीडर और जज चलाता है। डिफ़ॉल्ट claude है।
• --file <path> — evals फ़ाइल। डिफ़ॉल्ट evals.yaml है।
• --threshold <0..1> — रन के ग़ैर-शून्य एग्ज़िट देने से पहले न्यूनतम पासिंग अंश। डिफ़ॉल्ट 1 है।
• --timeout <seconds> — प्रति प्रश्न रीडर की समय-सीमा। डिफ़ॉल्ट 180 है।
• --json — रिपोर्ट को stdout पर JSON के रूप में देता है।
• --fix — विफल रन के बाद, डॉक्स को इंटरैक्टिव रूप से ठीक करने के लिए रिपोर्ट एजेंट को सौंप देता है।
• --verbose — हर विफलता के नीचे रीडर का पूरा उत्तर शामिल करता है।