Практичні нотатки: Оцінювання: Короткий курс для агентів та навичок

Наведені нижче примітки описують практичний підхід до вивчення матеріалу «Evals: A Crash Course for Agents and Skills». Основна увага приділяється контрактам, перевіркам та місцям для вставки коду, а не мотиваційним аспектам. Під час роботи на етапі огляду спочатку запишіть контракт: необхідні вхідні дані, сигнал про успіх та наслідки часткової невдачі. Такий перелік допоможе зберегти чесність пізніших змін у коді. Тримайте конфігурацію окремо від коду додатку. Файли середовища, сховища секретних даних та флаги функцій мають знаходитися в одному місці, яке оператори можуть перевірити, не читаючи весь код.

Ментальна модель

Етап створення ментальної моделі працює найкраще, коли його розглядають як вимірювану поверхню. Запишіть один ідеальний приклад роботи, один випадок невдачі та примітки щодо скасування змін перед розширенням обсягу завдань. Документуйте як успішний, так і відновлювальний сценарії роботи. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої доробки. Визначте бюджет на кількість операцій за раз та за сеанс. Інструменти типу агентів активно розширюють контекст; жорсткі обмеження запобігають тому, щоб демонстрації перетворювалися на несподівані рахунки.

Шари оцінки

Етапи шарів оцінки працюють найкраще, якщо їх розглядати як вимірювану поверхню. Збережіть один ідеальний зразок результату, один випадок невдачі та примітку про скасування змін перед розширенням обсягу роботи. Віддавайте перевагу невеликим, тестованим одиницям перед складними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність дій. Зберігайте стан графа у випрямленому та типованому форматі. Вкладені структури приховують інформацію про те, який вузол заповнив яке поле, і ускладнюють продовження роботи після перерв.

Для навичок потрібні два набори оцінювання

The Skills need two eval stage works best when treated as a measurable surface. Зафіксуйте один ідеальний приклад роботи, один випадок збою та примітку щодо скасування змін перед розширенням обсягу завдань. Розглядайте цю стадію як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте мовчазного часткового виконання завдань. Зберігайте структуру графа у простому та типованому вигляді. Вкладені елементи приховують інформацію про те, який вузол заповнив певне поле, що ускладнює продовження роботи після перерв. The Skills need two eval stage works best when treated as a measurable surface. Зафіксуйте один ідеальний приклад роботи, один випадок збою та примітку щодо скасування змін перед розширенням обсягу завдань. Зберігайте конфігурацію окремо від коду програми. Файли середовища, бази зберігання секретних даних та флаги функцій мають знаходитися в одному місці, щоб оператори могли їх перевіряти, не читаючи весь граф.

- prompt: "Patch the vulnerable npm dependencies"
  expected_skill: cve-remediation
- prompt: "Review authentication input validation"
  forbidden_skill: cve-remediation

Як має виглядати хороший випадок оцінки

Для етапу оцінки «Яка чудова оцінка» необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не здогадуючись про прихований стан. Необхідно документувати як шлях успішного виконання, так і шлях відновлення. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації. Встановлюйте людське схвалення для тих кроків, які призводять до витрат грошей або змінюють дані у продакшені. Підключення на етапі компіляції не є гарантією повності функціоналу продукту.

{
  "id": "fix-null-condition",
  "prompt": "Fix saving rules with a null condition",
  "fixture": "repos/null-condition",
  "setup": ["npm install"],
  "checks": [
    "npm test -- null-condition.test.js",
    "git diff --check"
  ],
  "rubric": [
    "Fixes the root cause",
    "Preserves existing behavior",
    "Adds a regression test",
    "Avoids unrelated changes"
  ],
  "forbidden": [
    "deleting existing tests",
    "hard-coded fixture-specific output"
  ]
}

Оцінювачі: використовуйте найсильніший з доступних

Для оцінювачів слід використовувати найсильнішу стадію, визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не здогадуючись про прихований стан. Краще використовувати маленькі, перевірювані одиниці ніж величезні скрипти. Коли крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану систему обробки даних. Необхідно включати людське схвалення для операцій, які призводять до витрат грошей чи змінюють продуктивні дані. Підключення на етапі компіляції не є гарантією повноти бізнес-функцій.

Важливі показники

На етапі «Метрики, які мають значення» необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Призначте назви артефактів, визначте критерії успіху та не допускайте беззвучного часткового завершення. Забезпечте людське схвалення для операцій, які призводять до витрат грошей чи змінюють дані у продакшені. Підключення під час компіляції не є гарантією повноти бізнес-процесу. На етапі «Метрики, які мають значення» необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Зберігайте конфігурацію окремо від коду додатку. Файли середовища, сховища секретних даних та флаги функцій мають знаходитися в одному місці, яке оператори можуть перевірити, не читаючи весь кодовий граф.

Створення якісного набору даних

Під час роботи над етапом створення якісного набору даних спочатку запишіть умови виконання: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність подальших змін у коді. Одночасно задокументуйте шлях успішного виконання та шлях відновлення. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації. Робіть контрольні позначки після дорогих операцій. Функція відновлення не повинна знову стягувати плату за той самий виклик LLM, коли оператор повторює спробу обробки пізнішого етапу.

Практичний цикл

Під час роботи над етапом «Практичний цикл» спочатку запишіть контракт: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Віддавайте перевагу невеликим, тестованим одиницям перед об’ємними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність операцій. Робіть перевірки після дорогих кроків. Система відновлення не повинна знову оплачувати один і той самий виклик LLM, коли оператор намагається знову виконати пізнішу операцію.

Поширені помилки

Під час роботи над етапом «Поширені помилки» спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність у подальших змінах коду. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте беззвучного часткового виконання завдань. Робіть перевірки після дорогих кроків. Система повернення до виконання не повинна знову стягувати плату за один і той самий виклик LLM, коли оператор намагається виконати наступний етап. Під час роботи над етапом «Поширені помилки» спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність у подальших змінах коду. Зберігайте конфігурацію окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код.

Метрики маршрутизації у конкретних формулах

Метрики маршрутизації, які описують конкретні етапи роботи, найкраще використовувати як вимірювану основу. Збережіть один ідеальний приклад виконання, один випадок збою та примітки щодо скасування змін перед розширенням обсягу роботи. Документуйте як успішний, так і відновлювальний сценарії роботи. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації. Зберігайте стан графа у простій та типованій формі. Вкладені структури приховують інформацію про те, який вузол заповнив яке поле, що ускладнює продовження роботи після перерв.

Найкраще місце для початку

Найкраще місце для реалізації проектів працює найефективніше, коли його розглядають як вимірювану поверхню. Запишіть один ідеальний приклад виконання, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Віддавайте перевагу невеликим, тестованим одиницям перед об’ємними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на складну послідовність дій. Зберігайте стан графа у простому та типованому вигляді. Вкладені структури приховують інформацію про те, який вузол заповнив яке поле, що ускладнює продовження роботи після перерв.

Справжня, мінімалістична фреймворк для оцінки, яку можна скопіювати

Справжній мінімальний етап оцінки працює найкраще, коли його розглядають як вимірювану поверхню. Збережіть один ідеальний зразок виконання, один випадок збою та примітку щодо скасування змін перед розширенням обсягу роботи. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте мовчазного часткового виконання завдань. Зберігайте стан графа у випрямленому та типованому форматі. Вкладені структури приховують інформацію про те, який вузол заповнив певне поле, що ускладнює продовження роботи після перерв. Справжній мінімальний етап оцінки працює найкраще, коли його розглядають як вимірювану поверхню. Збережіть один ідеальний зразок виконання, один випадок збою та примітку щодо скасування змін перед розширенням обсягу роботи. Зберігайте конфігурацію поза кодом програми. Файли середовища, бази зберігання секретних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь граф.

evals/
  cases/
    skills/security-review.trigger.json
    agents/fix-null-condition.json
  graders.py
  metrics.py
  runner.py
  run.py        # CLI entry1. Case files. A skill trigger case is just positives and negatives. An agent case is a prompt plus graders and a run count.

// cases/skills/security-review.trigger.json
{
  "skill": "security-review",
  "positives": [
    "Audit this endpoint for SQL injection",
    "Check the login flow for auth bypasses",
    "Is this file-upload handler safe?"
  ],
  "negatives": [
    "Upgrade React dependencies",
    "Rename this variable across the repo",
    "Add a loading spinner to the form"
  ]
}

// cases/agents/fix-null-condition.json
{
  "id": "fix-null-condition",
  "prompt": "Fix saving rules with a null condition",
  "fixture": "fixtures/null-condition",
  "setup": ["npm ci"],
  "runs": 5,
  "graders": [
    { "type": "shell", "cmd": "npm test -- null-condition", "critical": true },
    { "type": "shell", "cmd": "git diff --check" },
    { "type": "forbidden", "pattern": "it\\.skip|xit\\(", "message": "must not disable tests" }
  ]
}

# graders.py
import re, subprocess
def shell(step, ctx):
    r = subprocess.run(step["cmd"], cwd=ctx.workdir, shell=True,
                       capture_output=True, text=True)
    ok = r.returncode == 0
    return {"pass": ok, "score": 1 if ok else 0, "detail": r.stdout[-400:]}
def forbidden(step, ctx):
    bad = re.search(step["pattern"], ctx.diff) is not None
    return {"pass": not bad, "score": 0 if bad else 1,
            "detail": step["message"] if bad else ""}
def judge(step, ctx):
    v = ctx.llm.rate(step["rubric"], ctx.artifact)  # 0..1, blinded
    return {"pass": v >= step.get("threshold", 0.7), "score": v}
GRADERS = {"shell": shell, "forbidden": forbidden, "judge": judge}3. Metrics. Success rate, pass@k, pass^k, and the routing confusion matrix — exactly the numbers from earlier.

# metrics.py
def success_rate(rs):
    return sum(1 for r in rs if r["pass"]) / len(rs)
def pass_at_k(rs):
    return 1 if any(r["pass"] for r in rs) else 0
def pass_hat_k(rs):
    return 1 if all(r["pass"] for r in rs) else 0
def routing(positives, negatives, fired):
    tp = sum(1 for p in positives if fired(p))
    fp = sum(1 for n in negatives if fired(n))
    fn = len(positives) - tp
    tn = len(negatives) - fp
    return {"tp": tp, "fp": fp, "fn": fn, "tn": tn,
            "precision": tp / (tp + fp or 1),
            "recall": tp / (tp + fn or 1)}4. The runner. One function per suite. The agent runner repeats each case so pass^k is meaningful; the skill runner just asks the router which skills fire.

# runner.py
import json
from graders import GRADERS
from metrics import success_rate, pass_at_k, pass_hat_k, routing
def run_agent_case(agent, path):
    c = json.load(open(path))
    runs = []
    for _ in range(c.get("runs", 3)):
        ctx = agent.run(c["prompt"], fixture=c["fixture"], setup=c["setup"])
        ok = True
        for step in c["graders"]:
            g = GRADERS[step["type"]](step, ctx)
            if step.get("critical") and not g["pass"]:
                ok = False
        runs.append({"pass": ok})
    return {"id": c["id"], "success": success_rate(runs),
            "pass_at_k": pass_at_k(runs), "pass_hat_k": pass_hat_k(runs)}
def run_skill_trigger(router, path):
    c = json.load(open(path))
    fired = lambda prompt: c["skill"] in router.route(prompt)
    return {"skill": c["skill"], **routing(c["positives"], c["negatives"], fired)}5. Run it. The CLI just dispatches on the case type and prints the metrics.

$ python run.py cases/agents/fix-null-condition.json
fix-null-condition   success=0.80   pass@5=1.00   pass^5=0.20
$ python run.py cases/skills/security-review.trigger.json
security-review      precision=0.86  recall=1.00   (tp=6 fp=1 fn=0 tn=5)

Не створюйте все з нуля, якщо це не є необхідним

Щоб уникнути створення всього з нуля, спочатку визначте вхідні дані, відповідальну особу за кожен етап та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити етап з відомої точки контролю, не намагаючись вгадати прихований стан. Документуйте як успішний, так і відновлювальний сценарії роботи. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації. Встановлюйте людське схвалення для тих етапів, які призводять до витрат грошей чи змінюють дані виробництва. Підключення на етапі компіляції не є гарантією повноти функціоналу продукту.

Загальна оцінка LLM та запитів

На етапі оцінки запитів загальних ШІ-моделей необхідно визначити вхідні дані, відповідального за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись відгадати прихований стан. Краще використовувати невеликі, тестовані одиниці замість об’ємних скриптів. Коли крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність операцій. Коли наступним кроком є код або виклик інструменту, краще використовувати структуровані результати з перевіркою схеми, ніж вільний текст.

Відстеження, набори даних та платформи з ШІ як суддею

Для етапу платформ типу LLM-as-judge у наборах даних Tracing необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте безповідомного часткового завершення. У разі, коли наступним кроком є код або виклик інструменту, віддавайте перевагу структурованим результатам із перевіркою схеми перед вільним текстом. Для етапу платформ типу LLM-as-judge у наборах даних Tracing необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Зберігайте конфігурацію окремо від коду програми. Файли середовища, сховища секретів та флаги функцій мають знаходитися в одному місці, яке оператори можуть перевіряти без необхідності читання коду.

весь граф.

Інструменти та критерії оцінки для конкретних агентів

Під час роботи над етапом тестування інструментів та критеріїв оцінки для конкретних агентів спочатку запишіть умови використання: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Документуйте як шлях успішної роботи, так і шлях відновлення. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації. Фіксуйте назву інструменту, хеш аргументів, час виконання та результат кожного виклику. Без цих записів налагодження ланцюгів агентів займає години.

Як вибрати

Під час роботи над етапом «Як вибрати», спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Віддавайте перевагу невеликим, тестованим одиницям коду перед об’ємними скриптами. Якщо якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність операцій. Робіть перевірки після дорогих кроків. Система повинна не стягувати знову плату за один і той самий виклик LLM, коли оператор перезапускає пізніший етап.

Чек-лист для експлуатації

На етапі чек-листу для експлуатації визначте вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не здогадуючись про прихований стан.

Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Візуальний контроль витрат заздалегідь запобігає несподіваним рахункам під час переходу з демо-середовища у спільні.

Встановлюйте людське схвалення для операцій, які спричиняють витрати чи змінюють дані у продакшені. Підключення під час компіляції не гарантує повноти бізнес-функціоналу.

Відстежуйте витрати та затримки разом із якістю. Трохи гірша відповідь, яка коштує в 10 разів менше, може бути оптимальним вибором для продакшену.

Фіксуйте версії залежностей та записуйте дайджест зображення, яке використовувалося під час демонстрації. Відтворюваність краща за індивідуальні знання спеціалістів.

Віддавайте перевагу малим, тестованим одиницям коду перед складними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність операцій.

Перш ніж запускати стек у продакшн, заморозьте версії, створіть «золотий» запис для критичного шляху та підтвердьте кроки відкату. У спільних середовищах необхідні обмеження на частоту запитів, перевірки прав доступу та чіткий власник для зміни секретів. Віддавайте перевагу надійності перед креативними одноразовими демонстраціями.

Примітка для ce69f1512f25: не зберігайте ключі постачальника у репозиторії, встановіть ліміт токенів на сеанс та зберігайте записи поруч із фікстурами для оцінки, щоб подальша заміна моделей залишалася порівнянною.