DSPy — Автоматична генерація промптів
Ця стаття для тих, хто робить агентів і ланцюжки викликів на LLM і втомився добирати промпт руками. Для простого завдання вистачає промпту в дусі «Ти розумний помічник, відповідай на питання». Але коли агент викликає функції й розбирає нестандартні запити, промпт розростається до кількох сторінок правил, а після зміни моделі перестає працювати, і все доводиться добирати заново. Як писати такі промпти руками, розібрано в статті про промпт-інжиніринг, а як агент викликає інструменти — у статті про RAG і виклик функцій.
DSPy (GitHub) пропонує інший шлях. Завдання описують кодом: що надходить на вхід, що потрібно отримати і з яких кроків складається програма. Текст промпту DSPy збирає сам. А якщо є приклади з правильними відповідями і функція, яка оцінює відповідь, оптимізатор добирає для кожного кроку інструкцію і приклади, на яких оцінка вища. Змінили модель — запустили добір заново, замість того щоб переписувати текст.
Фреймворк з'явився у Стенфорді, у групі Stanford NLP. Його автор — Омар Хаттаб, перша стаття про нього вийшла в жовтні 2023 року. Назва розшифровується як Declarative Self-improving Python, а девіз проєкту — «програмувати, а не писати промпти».
У статті один наскрізний приклад: агент підтримки інтернет-магазину, який відповідає на питання покупців за базою знань у SQLite. Спочатку розберемо основні поняття, потім підключимо модель, опишемо завдання, зберемо агента з інструментом, навчимося його оцінювати, налаштуємо двома оптимізаторами, MIPROv2 і GEPA, і збережемо результат. Код перевірено на DSPy 3.4.1, останньому випуску на листопад 2026 року, з локальною моделлю Gemma 4 E4B у LM Studio. Виводи програм і виміри в статті — з цього прогону, а де цифру взято з документації або пораховано на підставній моделі, це сказано поруч.
Плюси: промпт перестає бути «магічним текстом» — замість нього є код, метрика і відтворюваний результат. Зміна моделі перетворюється на повторний запуск налаштування з оцінкою до і після. Маленька модель після налаштування нерідко наздоганяє велику, яку ніхто не налаштовував.
Мінуси: потрібні приклади з правильними відповідями і спосіб оцінити відповідь, без них налаштовувати нічого. Налаштування триває від десятків хвилин до годин і може коштувати грошей. API швидко змінюється: між версіями 3.0 і 3.5 перероблено агентів, підключення моделей і адаптери. Готовий промпт пише машина, і правити його руками незручно.
З чого складається DSPy
Які поняття потрібно знати
У DSPy свій словник, і без нього документацію читати важко. Ось слова, які трапляться далі:
- LM (language model) — підключення до моделі: який сервер, яка модель, з якими параметрами.
- Сигнатура — опис завдання: які поля надходять на вхід, які потрібно повернути і що вони означають. Це заміна тексту промпту.
- Модуль — спосіб розв'язати завдання за сигнатурою.
Predictпросто питає модель,ChainOfThoughtпросить спершу поміркувати,ReActперетворює модель на агента, який викликає інструменти. - Предиктор — один виклик моделі всередині модуля зі своєю сигнатурою, інструкцією і прикладами. У простому модулі він один, в агенті їх кілька. Оптимізатор налаштовує саме предиктори.
- Адаптер — перекладач між сигнатурою і моделлю. Він перетворює сигнатуру на повідомлення чату, а відповідь моделі — назад на поля Python.
- Приклад (
dspy.Example) — один запис набору даних: питання і правильна відповідь. - Метрика — звичайна функція Python, яка каже, наскільки добра відповідь програми на один приклад.
- Оптимізатор — алгоритм, який багато разів запускає програму на прикладах і змінює інструкції та приклади в промптах (а деякі — і ваги моделі), щоб підняти метрику. У старих версіях оптимізатори називалися телепромптерами, це слово досі трапляється в коді.
Пов'язані вони так. Модуль виконує сигнатуру. Адаптер перетворює її на повідомлення для LM і розбирає відповідь. Метрика оцінює результат на прикладах. Оптимізатор переписує інструкції та добирає приклади всередині предикторів, доки метрика не перестане зростати.
Підключення моделі
Як встановити DSPy і підключити модель
DSPy встановлюється як звичайний пакет Python, працює на Python від 3.10 до 3.15:
pip install -U "dspy[optuna]"Доповнення optuna потрібне оптимізатору MIPROv2. З версії 3.2 ця бібліотека не встановлюється за замовчуванням, і без неї MIPROv2 падає з помилкою імпорту. Оптимізатор GEPA встановлюється разом із DSPy, крім Python 3.15: його пакет gepa поки підтримує лише версії до 3.14.
Тепер підключимо модель. У прикладі це Gemma 4 E4B, запущена в LM Studio на цьому ж комп'ютері:
import dspy
# Префікс openai/ означає «сервер з тим самим API, що в OpenAI»,# після нього йде назва моделі на цьому сервері.lm = dspy.LM( "openai/google/gemma-4-e4b", api_base="http://localhost:1234/v1", api_key="lm-studio", # LM Studio ключ не перевіряє, але поле обов'язкове temperature=0,)# Тепер цю модель використовують усі модулі, якщо не вказано інше.dspy.configure(lm=lm)Модель задається рядком «провайдер/модель». Для хмарної моделі змінюється лише рядок, наприклад openai/gpt-5.4-nano, а адресу сервера вказувати не потрібно. Ключ береться зі змінної середовища провайдера, наприклад OPENAI_API_KEY. Під капотом DSPy звертається до моделей через бібліотеку LiteLLM, а з версії 3.4 там, де може, — через власний рушій lm15. Рядок із моделлю в них спільний, тому код від вибору рушія не змінюється.
temperature=0 майже прибирає випадковість: модель обирає найімовірнішу відповідь. Зовсім однаковими відповіді все одно не будуть — у наших прогонах агент на повторне питання іноді шукав іншими словами, — але розкид стає меншим. Для агента і для чесного порівняння «до і після» це зручно.
Чому повторний запуск майже безкоштовний
DSPy запам'ятовує відповіді моделі. Кеш лежить у пам'яті та на диску, у теці ~/.dspy_cache, і за замовчуванням займає до 30 ГБ. Якщо запит у точності повторюється (той самий промпт, та сама модель, ті самі параметри), він не йде в модель, а відповідь береться з кешу.
Для оптимізації це велика економія: перерваний прогін можна запустити знову, і все, що вже пораховано, повториться миттєво. Але кеш заважає вимірювати швидкість і перевіряти, наскільки модель стабільна: другий запуск виявиться підозріло швидким і в точності таким самим, як перший. Для таких вимірів кеш вимикають параметром cache=False у dspy.LM.
Сигнатура
Що таке сигнатура
Сигнатура описує завдання як функцію: що на вході і що на виході. Найкоротший запис — рядок, де входи й виходи розділені стрілкою:
qa = dspy.Predict("question -> answer")result = qa(question="What is the capital of France?")print(result.answer) # ParisPredict — найпростіший модуль: один виклик моделі без міркувань та інструментів. Результат — об'єкт Prediction, у якого поля називаються так само, як виходи сигнатури.
Що DSPy надсилає моделі
Промпт ми не писали, але модель його отримала. Подивитися, що саме пішло в модель і що прийшло назад, можна одним рядком:
dspy.inspect_history(n=1) # n — скільки останніх викликів показатиSystem message:
Your input fields are:1. `question` (str):Your output fields are:1. `answer` (str):All interactions will be structured in the following way, with the appropriate values filled in.
[[ ## question ## ]]{question}
[[ ## answer ## ]]{answer}
[[ ## completed ## ]]In adhering to this structure, your objective is: Given the fields `question`, produce the fields `answer`.
User message:
[[ ## question ## ]]What is the capital of France?
Respond with the corresponding output fields, starting with the field `[[ ## answer ## ]]`, and then ending with the marker for `[[ ## completed ## ]]`.
Response:
[[ ## answer ## ]]Paris
[[ ## completed ## ]]Це робота адаптера ChatAdapter, який DSPy використовує за замовчуванням. У системному повідомленні він перелічує поля, показує формат і формулює мету. Мету поки зібрано з назв полів, бо інструкції ми не дали. У повідомленні користувача стоять значення вхідних полів. Маркери на кшталт [[ ## answer ## ]] потрібні, щоб потім знайти поля у відповіді: адаптер шукає їх і розкладає текст по полях.
Якщо модель порушила формат і адаптер не зміг розібрати відповідь, ChatAdapter сам повторює запит через JSONAdapter: той просить відповідь у вигляді JSON і, якщо сервер уміє, вмикає режим суворого JSON. Є й інші адаптери, наприклад XMLAdapter. Змінити адаптер для всієї програми можна так: dspy.configure(adapter=dspy.JSONAdapter()).
Маленькі моделі іноді порушують формат непомітно. В одному з наших прогонів Gemma 4 E4B не поставила перенесення рядка перед фінальним маркером, і останнє поле прийшло з хвостом: $15[[ ## completed ## ]]. Помилки не було, просто у відповіді опинилося сміття. Тому перше, що варто зробити з новою моделлю, — подивитися на inspect_history на власні очі.
Як описати сигнатуру класом
Для справжнього завдання сигнатуру пишуть класом. Тоді в полів з'являються типи й описи, а рядок документації класу стає інструкцією для моделі:
from typing import Literal
class ClassifyTicket(dspy.Signature): """Classify a customer support ticket."""
text: str = dspy.InputField() # Literal обмежує відповідь переліком значень, bool — значеннями True і False. topic: Literal["delivery", "refund", "payment", "other"] = dspy.OutputField() urgent: bool = dspy.OutputField(desc="the customer is blocked or very upset")
classify = dspy.Predict(ClassifyTicket)result = classify(text="My parcel is two weeks late and I need it for a birthday tomorrow!")print(result.topic, result.urgent) # delivery Trueresult.urgent тут справжній bool, а не рядок "True": адаптер зводить відповідь до типу поля. Підійдуть int, float, list[str], dict, Literal і моделі Pydantic. Якщо відповідь до типу не зводиться, адаптер повідомить про помилку, а не поверне сміття.
Щоб модель знала про обмеження, адаптер дописує їх у промпт. Ось як поля цієї сигнатури виглядають у системному повідомленні:
[[ ## topic ## ]]{topic} # note: the value you produce must exactly match (no extra characters) one of: delivery; refund; payment; other
[[ ## urgent ## ]]{urgent} # note: the value you produce must be True or FalseРядок документації — Classify a customer support ticket. — став метою в системному повідомленні замість безликого «Given the fields...». Саме цю інструкцію оптимізатор потім переписуватиме. Описів полів (desc) він не чіпає, тому в них варто писати те, що має лишитися незмінним.
Рядки документації та описи полів ми пишемо англійською: це текст, який читає модель, а не програміст. Для невеликих моделей англійська зазвичай надійніша.
Чим Predict відрізняється від ChainOfThought
ChainOfThought приймає ту саму сигнатуру, але додає перед вихідними полями ще одне — reasoning. Модель спершу пише міркування, потім відповідь:
think = dspy.ChainOfThought(ClassifyTicket)result = think(text="Can I pay with Apple Pay?")print(result.topic, result.urgent) # payment Falseprint(result.reasoning) # The customer is asking a question regarding accepted methods of payment...Сигнатуру змінювати не довелося. У цьому і сенс модулів: завдання описано один раз, а спосіб його розв'язання змінюється одним рядком. Міркування допомагає в завданнях, де треба щось порахувати або зіставити, але подовжує відповідь і сповільнює виклик.
Агент з інструментами
Як підготувати базу знань
Агенту потрібне джерело фактів. У прикладі це база знань магазину в SQLite: дванадцять коротких статей про повернення, доставку, оплату, гарантію і так далі. Ось перші чотири і створення таблиці:
import sqlite3
ARTICLES = [ ("Refunds", "You can return an item within 30 days of delivery for a full refund. " "The money goes back to the original payment method within 5 business days " "after the warehouse receives the item."), ("Return shipping", "Return shipping is free for defective items. For any other return, " "a flat fee of $6 is deducted from the refund."), ("Delivery times", "Standard delivery takes 3 to 5 business days. Express delivery takes " "1 to 2 business days and costs $12."), ("Payment methods", "We accept Visa, Mastercard, PayPal and Apple Pay. " "Cash on delivery is not available."), # Ще вісім статей у тому самому вигляді: безкоштовна доставка, доставка за кордон, # гарантія, зміна замовлення, подарункові картки, бонуси, гарантія найкращої ціни і підтримка.]
# FTS5 — вбудований у SQLite повнотекстовий пошук. Така таблиця# зберігає текст і одразу будує за ним індекс слів.db = sqlite3.connect("kb.db")db.execute("DROP TABLE IF EXISTS articles")db.execute("CREATE VIRTUAL TABLE articles USING fts5(title, text)")db.executemany("INSERT INTO articles VALUES (?, ?)", ARTICLES)db.commit()db.close()FTS5 зазвичай уже є в SQLite, який постачається з Python, нічого встановлювати не потрібно. Повнотекстовий пошук потрібен, бо запит до бази пише модель, а вона формулює його по-своєму.
Як описати інструмент
Інструмент для DSPy — звичайна функція Python. Важливо лише, щоб у неї були зрозуміла назва, підказки типів для аргументів і рядок документації: DSPy показує все це моделі, і за ними вона вирішує, коли і як викликати функцію.
import refrom contextlib import closing
def search_kb(query: str) -> list[str]: """Search the shop's knowledge base and return up to 3 matching articles.""" # 1. Лишаємо від запиту тільки слова: лапки й зірочки # FTS5 сприйняв би за свій синтаксис. words = re.findall(r"\w+", query) if not words: return [] # 2. OR: підходить стаття, де є хоча б одне слово запиту. # bm25 ставить вище статті, де збігів більше. match = " OR ".join(f'"{word}"' for word in words) # closing закриває з'єднання: звичайний with у sqlite3 керує лише транзакцією. with closing(sqlite3.connect("kb.db")) as db: rows = db.execute( "SELECT title, text FROM articles WHERE articles MATCH ? " "ORDER BY bm25(articles) LIMIT 3", (match,), ).fetchall() # 3. Модель отримає список рядків вигляду «заголовок: текст». return [f"{title}: {text}" for title, text in rows]
print(search_kb("cash on delivery")[0]) # Payment methods: We accept Visa, Mastercard, PayPal and Apple Pay. ...Чому не LIKE '%...%'. Модель вигадує запит сама, наприклад refund period. LIKE шукає цю фразу цілком, а в тексті статті слова «refund» і «period» стоять окремо або їх немає зовсім. Агент отримав би порожній список і вирішив би, що відповіді в базі немає. Пошук за словами з ранжуванням прощає чужі формулювання. У справжньому проєкті тут зазвичай стоїть векторний пошук, про нього розказано в статті про векторні бази даних, але для DSPy це нічого не змінює: інструмент лишається функцією.
Ось як DSPy описує цей інструмент моделі. Це фрагмент промпту агента, про який нижче:
(1) search_kb, whose description is <desc>Search the shop's knowledge base and return up to 3 matching articles.</desc>. It takes arguments {'query': {'type': 'string'}}.(2) finish, whose description is <desc>Marks the task as complete. That is, signals that all information for producing the outputs, i.e. `answer`, are now available to be extracted.</desc>. It takes arguments {}.Назву функції, рядок документації і схему аргументів узято з коду. Тому невдала назва на кшталт f1 або порожній рядок документації погіршують роботу агента так само, як погано написаний промпт. Інструмент finish ми не оголошували: його додає сам ReAct, щоб модель могла сказати «інформації досить».
Як зібрати агента
Сигнатура агента описує завдання цілком, без згадки про інструменти:
class AnswerFromKb(dspy.Signature): """Answer the customer's question using only the shop's knowledge base."""
question: str = dspy.InputField() answer: str = dspy.OutputField(desc="a short answer, no explanations")
agent = dspy.ReAct(AnswerFromKb, tools=[search_kb], max_iters=5)result = agent(question="How long is the refund period?")print(result.answer) # You can return an item within 30 days of delivery for a full refund.max_iters обмежує кількість кроків: якщо модель так і не скаже finish, агент зупиниться після п'ятого виклику інструмента. За замовчуванням кроків двадцять.
Відповідь правильна, але довга, хоча в описі поля ми просили коротко і без пояснень. Маленька модель такі прохання часто пропускає. До цього ми повернемося, коли писатимемо метрику: саме такі речі оптимізація і виправляє.
Що відбувається всередині ReAct
ReAct (від reasoning and acting — «міркуй і дій») — цикл, у якому модель по черзі думає і викликає інструменти. У DSPy 3.4 він влаштований так:
- Модель отримує питання, перелік інструментів та історію минулих кроків. На першому кроці історія порожня.
- Модель пише думку (
next_thought), обирає інструмент (next_tool_name) і аргументи для нього (next_tool_args). - DSPy викликає функцію, а її результат (
observation) дописує в історію. - Кроки 2 і 3 повторюються, доки модель не обере
finishабо не скінчитьсяmax_iters. - Окремий виклик моделі,
extract, читає всю історію і заповнює вихідні поля сигнатури, у нас —answer. Він влаштований якChainOfThought, тому спершу теж міркує.
Виходить, що всередині агента два предиктори: react обирає кроки, extract пише відповідь. У кожного своя інструкція і свої приклади, і оптимізатор налаштовує обидва. Це знадобиться, коли дивитимемося на результат оптимізації.
Історію кроків можна подивитися в полі trajectory (довгі рядки у виводі скорочено):
for key, value in result.trajectory.items(): print(f"{key}: {value}")thought_0: The user wants to know the duration of the refund period. I need to search the knowledge base using relevant keywords like "refund period" or "return policy" to find this information.tool_name_0: search_kbtool_args_0: {'query': 'refund period'}observation_0: ['Price match: If you find a lower price at another official retailer within 14 days of purchase, we refund the difference.', 'Return shipping: ...', 'Refunds: You can return an item within 30 days of delivery for a full refund. ...']thought_1: The previous search provided a clear answer in observation [3]. It states: "You can return an item within 30 days of delivery for a full refund." ... I will finish the task.tool_name_1: finishtool_args_1: {}observation_1: Completed.Модель шукала за словами refund period, і потрібна стаття опинилася третьою: слово «refund» трапляється в трьох статтях, а «period» — у жодній. Модель однаково знайшла відповідь і закінчила роботу. На три виклики моделі пішло близько дев'яти секунд.
Ще дві речі, які ReAct робить сам. Якщо інструмент кинув виняток, агент не падає: текст помилки потрапляє в історію замість результату, і модель може спробувати інакше. Якщо історія перестала вміщатися в контекст моделі, ReAct викидає найстаріші кроки і пробує знову, до трьох разів.
Що зміниться в DSPy 3.5
В основній гілці DSPy, з якої вийде версія 3.5, ReAct уже переписано. Нова реалізація є і в 3.4, під назвою dspy.ReActV2, з позначкою «експериментальна». Відмінності такі:
- Минулі кроки передаються моделі як справжній діалог із викликами функцій, а якщо адаптер це підтримує, використовується вбудований в API провайдера виклик функцій. За один крок можна викликати кілька інструментів.
- Замість
finishі окремого крокуextractмодель викликає інструментsubmitі одразу передає в ньому готові вихідні поля. Предиктор всередині агента лишається один. - Замість
trajectoryу результаті будуть поляhistoryіtermination_reason, причина зупинки.
Код цієї статті переживе оновлення, крім циклу по trajectory вище. А от збережений результат оптимізації — ні: у нового агента інші предиктори, і налаштування доведеться запустити заново. Документація 3.4 радить для нових агентів уже зараз брати dspy.ReActV2, якщо вас не бентежить експериментальний API і ви закріпили версію DSPy у залежностях. У 3.5 назва ReActV2 лишиться як застарілий псевдонім, а в 3.6 її приберуть.
Дані
Як виглядає набір даних
Набір даних — це список питань із правильними відповідями. Найпростіше зберігати його в JSON:
[ { "question": "How long is the refund period?", "answer": "30 days" }, { "question": "How much does it cost to return a jacket that I just didn't like?", "answer": "$6" }]DSPy працює не зі словниками, а з об'єктами dspy.Example:
import json
with open("dataset.json", encoding="utf-8") as f: examples = [dspy.Example(**row).with_inputs("question") for row in json.load(f)]
print(len(examples)) # 40print(examples[0].inputs()) # Example({'question': 'How long is the refund period?'}) (input_keys={'question'})print(examples[0].labels()) # Example({'answer': '30 days'}) (input_keys=None)with_inputs("question") каже, які поля прикладу — входи програми. Лише вони потраплять в агента під час запуску. Решта полів, тут answer, лишаються правильними відповідями, які побачить метрика. Якщо забути with_inputs, DSPy не зрозуміє, що подавати на вхід: кожен запуск закінчиться помилкою «Inputs have not been set for this example». На наборі з менш ніж десяти прикладів оцінка просто покаже нуль. Якщо прикладів десять і більше, dspy.Evaluate на десятій помилці здається й кидає виняток «Execution cancelled due to errors or interruption», а справжня причина видна лише в рядках ERROR над ним.
Скільки потрібно прикладів
Попередня документація DSPy давала такі орієнтири: тридцять прикладів часто вже приносять помітну користь, але прагнути варто щонайменше до трьохсот, а для MIPROv2 — до двохсот і більше, щоб оптимізатор не перенавчився. У документації 3.4, переписаній навколо GEPA, цих сторінок більше немає, їхній текст лишився тільки в репозиторії. Універсальних чисел нова документація не дає.
Важливіше за кількість — різноманіття. У нашому наборі сорок питань, і в ньому є:
- ті самі факти, запитані різними словами: «How long is a gift card valid?» і «When does a gift card expire?»;
- питання у два кроки, де треба знайти і порахувати: «If I return a sweater I don't like, how much of its $40 price do I get back?» — правильна відповідь $34;
- питання, де модель має здогадатися, яка стаття підходить, хоча слова в питанні інші.
У справжньому наборі варто додати питання, на які в базі немає відповіді: агент має чесно сказати «не знаю», а не вигадати правило. Сорока прикладів мало для справжнього налаштування, але для навчального прогону на локальній моделі саме те: один прогін MIPROv2 на них зайняв трохи більше години.
Як розділити дані
Дані ділять на три частини, і в кожної своя роль:
- навчальна (train): з неї оптимізатор бере приклади для промпту і матеріал для нових інструкцій;
- валідаційна (val): на ній оптимізатор порівнює кандидатів і обирає найкращого;
- тестова (test): її оптимізатор не бачить, і підсумкову оцінку рахують на ній.
Без тестової вибірки результат оманливий. Оптимізатор обрав промпт, який найкраще впорався з валідаційною вибіркою, тому оцінка на ній завжди завищена. Чесну картину дає лише вибірка, якої він не бачив.
Пропорції залежать від оптимізатора. Для більшості оптимізаторів промптів, зокрема MIPROv2, попередня документація радила незвичне розбиття: двадцять відсотків на навчання і вісімдесят на валідацію. Оптимізатори промптів легко підлаштовуються під маленьку навчальну вибірку, і стійка оцінка на великій валідаційній важливіша. Для GEPA все навпаки, до нього ми повернемося нижче. Розбиття для MIPROv2:
import random
# Перемішуємо з фіксованим зерном, щоб розбиття повторювалося.random.Random(0).shuffle(examples)
# 1. П'яту частину відкладаємо для підсумкової перевірки.test_size = len(examples) // 5testset, rest = examples[:test_size], examples[test_size:]
# 2. Залишок для MIPROv2: 20 % на навчання, 80 % на валідацію.train_size = len(rest) // 5trainset, valset = rest[:train_size], rest[train_size:]
print(len(trainset), len(valset), len(testset)) # 6 26 8Метрика
Що таке метрика
Метрика — функція, яка отримує приклад із правильною відповіддю і відповідь програми та повертає оцінку: True/False або число від 0 до 1. Що вважати доброю відповіддю, вирішуємо ми. Тут відповідь добра, якщо в ній є правильне значення і вона коротка, як ми й просили в сигнатурі:
def metric(example, prediction, trace=None): answer = prediction.answer.lower() # 1. У відповіді є правильне значення, наприклад «30 days». correct = example.answer.lower() in answer # 2. Відповідь коротка: не довша за десять слів. short = len(answer.split()) <= 10 return correct and shortТретій аргумент, trace, — історія викликів всередині програми. Під час звичайної оцінки він дорівнює None. Оптимізатор передає його, коли вирішує, чи годиться вдалий прогін у приклади для промпту, і в цей момент йому потрібна сувора відповідь «так» або «ні». Наша метрика і так повертає bool, тому trace можна не використовувати. Якщо метрика повертає дробову оцінку, за trace її перетворюють на так чи ні: наприклад, return score >= 0.8 if trace is not None else score.
Як оцінити агента
Оцінку на наборі даних запускає dspy.Evaluate. Вона проганяє програму по всіх прикладах, паралельно в кількох потоках, і рахує середнє:
evaluate = dspy.Evaluate(devset=testset, metric=metric, num_threads=4)report = evaluate(agent)print(report.score) # 50.0report.score — відсоток вдалих відповідей. У report.results лежать трійки «приклад, відповідь, оцінка», за ними зручно розбирати помилки:
for example, prediction, score in report.results: if not score: print(example.question, "->", prediction.answer)На тестовій вибірці агент упорався з половиною питань. На всіх сорока результат майже такий самий — 57,5 %, і повний прогін зайняв вісім хвилин. Невдачі там трьох видів:
How long is a gift card valid? -> Gift cards are valid for 3 years from the date of purchase.What is the price of express shipping? -> The knowledge base confirms that express delivery is never free, but it does not provide the specific price.How many loyalty points do I earn per dollar? -> One point per dollarПерша — найчастіша: відповідь правильна, але довша за десять слів. Друга — справжня помилка: стаття з ціною була в базі, але модель її не знайшла. Третя — помилка метрики: «One point» означає те саме, що «1 point», але підрядок не збігся. Такі хибні провали псують оптимізацію: оптимізатор старанно вчитиме модель писати цифрами те, що й словами було правильно. Тому, перш ніж налаштовувати програму, варто переглянути невдачі очима і переконатися, що метрика лає саме те, що потрібно.
Коли потрібен суддя на LLM
Підрядок добре працює для коротких фактів. Для вільних відповідей, де одну думку можна сказати сотнею способів, його замінюють суддею: ще однією програмою на DSPy, яка порівнює відповідь з еталоном за змістом.
class JudgeAnswer(dspy.Signature): """Decide whether the answer gives the same facts as the reference answer."""
question: str = dspy.InputField() reference: str = dspy.InputField() answer: str = dspy.InputField() is_correct: bool = dspy.OutputField()
judge = dspy.ChainOfThought(JudgeAnswer)
def judge_metric(example, prediction, trace=None): verdict = judge(question=example.question, reference=example.answer, answer=prediction.answer) return verdict.is_correctСуддя коштує дорого: кожна оцінка тепер — ще один виклик моделі, а за оптимізацію оцінок тисячі. Він теж помиляється, тому для судді беруть модель сильнішу за ту, яку оцінюють. Окрему модель для судді задають через dspy.context(lm=...) навколо виклику. У DSPy є і готові метрики: dspy.evaluate.answer_exact_match порівнює відповіді після нормалізації тексту, а dspy.evaluate.SemanticF1 — суддя, який за змістом рахує, наскільки повно відповідь покриває еталон і чи немає в ній зайвого. Їм потрібні поля з певними назвами, тому свою метрику на десять рядків часто написати простіше.
Оптимізація
Які оптимізатори є
Оптимізатор може змінювати три речі: інструкції, приклади в промпті (їх називають демонстраціями, або few-shot) і ваги моделі. Кожен працює з однією-двома з них:
| Оптимізатор | Що змінює | Коли брати |
|---|---|---|
LabeledFewShot | приклади з даних як є | чесна точка відліку, викликів моделі не робить |
BootstrapFewShot | приклади з вдалих прогонів програми | перший розумний крок, майже завжди краще, ніж без прикладів |
BootstrapFewShotWithRandomSearch | те саме, багато наборів, найкращий за валідацією | коли один набір прикладів дає нестабільний результат |
MIPROv2 | інструкції та приклади разом | коли потрібно налаштувати і формулювання, і приклади |
GEPA | лише інструкції, за текстовими відгуками метрики | коли метрика може пояснити помилку словами і є сильна модель для розбору |
SIMBA | правила в інструкції та приклади для найважчих випадків | коли програма помиляється на окремих типах питань |
COPRO | лише інструкції, перебором | коли приклади вже добрі і заважають лише формулювання |
BootstrapFinetune | ваги моделі | останній важіль: потрібна модель, яку можна донавчати |
BetterTogether | ланцюжок з оптимізаторів промптів і донавчання | коли промпти і донавчання окремо вже пробували |
Сам DSPy оптимізатор не обирає. Документація радить починати з простого: якщо LabeledFewShot або BootstrapFewShot уже дають потрібний результат, важка оптимізація — зайві витрати. Донавчання ваг — останній засіб: коштує набагато дорожче, а приріст порівняно з GEPA або MIPROv2 часто дає невеликий. Зважайте і на ціну: за словами документації, один прогін GEPA або MIPROv2 на хмарних моделях може коштувати сотні доларів.
Як працює MIPROv2
MIPROv2 (Multiprompt Instruction Proposal Optimizer, друга версія) налаштовує інструкції та приклади одночасно. Працює він у три кроки:
- Збирання прикладів. Оптимізатор запускає програму на навчальній вибірці і запам'ятовує прогони, які метрика визнала вдалими. З них виходять набори прикладів для кожного предиктора, разом з усіма проміжними кроками: який інструмент викликано, що він повернув.
- Пропозиція інструкцій. Модель-«автор» отримує короткий опис даних, код програми, зібрані приклади і випадкову пораду на кшталт «будь стислим» або «будь креативним» і пише кілька варіантів інструкції для кожного предиктора.
- Пошук найкращої комбінації. Баєсівський пошук (алгоритм TPE з бібліотеки Optuna) пробує поєднання «інструкція і набір прикладів» для всіх предикторів одразу. Він запам'ятовує, які варіанти дають високий бал, і частіше пробує схожі.
Запуск виглядає так:
evaluate = dspy.Evaluate(devset=testset, metric=metric, num_threads=4)print("before:", evaluate(agent).score) # before: 50.0
optimizer = dspy.MIPROv2(metric=metric, auto="light", num_threads=4)tuned = optimizer.compile(agent, trainset=trainset, valset=valset)
print("after:", evaluate(tuned).score) # after: 87.5tuned.save("agent.json")compile не змінює вихідного агента, а повертає налаштовану копію. Тому agent і tuned можна порівняти на одній тестовій вибірці.
На тестовій вибірці частка вдалих відповідей зросла з 50 до 87,5 %: із восьми питань агент тепер упорується із сімома. На валідаційній вибірці найкращий кандидат набрав усі 100 % проти початкових 57,7 %. Різниця між 100 і 87,5 — та сама завищена оцінка, про яку йшлося під час розбиття даних: кандидата обирали за валідаційною вибіркою, тому на ній він виглядає краще, ніж на питаннях, яких не бачив.
Відповіді стали такими, як ми просили в сигнатурі:
How long is the refund period? -> 30 daysHow long after placing an order can I cancel it? -> Within 1 hourHow long does delivery to Canada take? -> 7 to 14 business daysWhen can I reach customer support? -> By chat, from 9:00 to 21:00 CET, seven days a week.Остання відповідь правильна, але в ній одинадцять слів, і метрика її не зарахувала.
Що саме змінилося, розберемо нижче, у розділі про результат. Коротко: обидва предиктори отримали нові інструкції, понад дві тисячі символів кожна. Для кроку extract це стрибок з одного рядка, а інструкція react і раніше була довгою, близько 1 200 символів, бо ReAct кладе в неї опис інструментів; оптимізатор переписав її повністю. Ще в кожного предиктора з'явилося по чотири приклади. Перший узято із записаного вдалого прогону агента: для extract це вся історія пошуку з підсумковою відповіддю, для react — лише перший крок, питання і перший виклик інструмента. Решта три — питання з навчальної вибірки з правильними відповідями на кшталт «$6» і «free». Їх бачить лише extract: у них немає жодного поля, яке видає крок react, тому адаптер не кладе їх у його промпт, і react насправді працює з одним прикладом.
Журнал спроб показує, що спрацювало. У двох спробах крок react налаштовано однаково, а в кроку extract немає прикладів і змінюється лише інструкція. Зі старою інструкцією оцінка на валідації — 53,8 %, з новою — 88,5 %. Найкращий результат дало поєднання нової інструкції з прикладами.
Прогін зайняв 65 хвилин на відеокарті ноутбука (RTX 5070 Ti): 14 хвилин на збирання прикладів та інструкцій і близько 50 на двадцять спроб. Агент за цей час запускався 555 разів. Час не еталонний, відеокарта була зайнята й іншими завданнями. Варіанти інструкцій писала та сама Gemma 4 E4B: окрему модель-«автора» ми не задавали.
Скільки коштує прогін MIPROv2
Параметр auto задає бюджет: light, medium або heavy. У режимі light MIPROv2 для нашого агента збирає шість наборів прикладів, готує по три варіанти інструкції для кожного з двох предикторів — вихідну і дві нові — і робить двадцять спроб. Кількість спроб рахується за формулою: дві змінні на предиктор (інструкція і приклади), усього чотири, і спроб виходить 2 × 4 × log₂ 6 ≈ 20.
Як оцінюється кожна спроба, залежить від розміру валідаційної вибірки. Режим light бере з неї не більше ста прикладів. Якщо їх більше п'ятдесяти, кожна спроба перевіряється на випадковій пачці з 35 прикладів, а найкращий кандидат раз на п'ять спроб проходить повну перевірку. Якщо п'ятдесят або менше, як у нас, кожна спроба перевіряється на всій вибірці.
Далі проста арифметика. На наборі з трьохсот прикладів (60 тестових, 48 навчальних, 192 валідаційних) MIPROv2 у режимі light запускає агента близько 1 230 разів. Ми порахували це на підставній моделі, яка відповідає миттєво і нічого не кешує. Кожен запуск агента — щонайменше три виклики моделі: пошук, finish і відповідь. Виходить близько чотирьох тисяч викликів. Зі справжньою моделлю частина повторів візьметься з кешу, але на хмарній моделі решта — прямі гроші.
Дві речі помітно знижують ціну. Перша — розділити моделі. Варіанти інструкцій пише prompt_model, а програму виконує task_model. «Автора» викликають рідко, тому його можна взяти сильнішим і дорожчим, а програму лишити на дешевій моделі:
optimizer = dspy.MIPROv2( metric=metric, auto="light", prompt_model=dspy.LM("openai/gpt-5.4"), # пише варіанти інструкцій task_model=lm, # виконує агента num_threads=4,)Друга — кеш, про який ішлося вище. Перерваний прогін під час повторного запуску проходить уже пораховану частину миттєво і безкоштовно.
Як працює GEPA
GEPA (від Genetic-Pareto) — оптимізатор, навколо якого тепер побудовано вступ у документації DSPy. Він змінює лише інструкції і робить це інакше, ніж MIPROv2: не перебирає готові варіанти, а читає, як програма помилилася, і переписує інструкцію так, щоб такої помилки не було. Цикл виглядає так:
- GEPA бере одного з найкращих кандидатів і запускає його на трьох прикладах з навчальної вибірки.
- Метрика оцінює відповіді і пояснює словами, що не так.
- Сильна модель (
reflection_lm) читає хід програми, відповіді й пояснення і пише нову інструкцію для одного з предикторів. - Якщо на тих самих прикладах стало краще, новий кандидат проходить перевірку на всій валідаційній вибірці і потрапляє в пул.
- У пулі живуть кандидати, які найкращі хоча б на одному прикладі, — це і є «фронт Парето» з назви. Іноді GEPA схрещує двох кандидатів, сильних на різних прикладах.
Головна відмінність — метрика. Їй можна повернути не тільки оцінку, а й відгук, і він дослівно потрапить до моделі, яка пише інструкцію. У метрики для GEPA п'ять аргументів: до звичайних додаються назва предиктора, який зараз налаштовується, і його частина історії викликів.
def gepa_metric(gold, pred, trace=None, pred_name=None, pred_trace=None): answer = pred.answer.lower() if gold.answer.lower() not in answer: return dspy.Prediction(score=0.0, feedback=f"Wrong. The correct answer is {gold.answer}.") words = len(answer.split()) if words > 10: return dspy.Prediction(score=0.5, feedback=f"Correct, but {words} words long. Use at most 10.") return dspy.Prediction(score=1.0, feedback="Correct and short.")Метрика може повернути і просто число, але тоді GEPA побачить лише «This trajectory got a score of 0.5», і його головна перевага зникне. Відгук пишемо англійською з тієї самої причини, що й інструкції: його читає модель.
Розбиття для GEPA протилежне розбиттю для MIPROv2. Кожен новий кандидат перевіряється на всій валідаційній вибірці, тож велика валідаційна вибірка з'їдає бюджет. Документація радить робити її якомога меншою, аби вона була схожа на справжні питання, а все інше віддавати в навчальну:
# Тестова вибірка та сама. Залишок ділимо навпаки:# три чверті на навчання, чверть на валідацію.val_size = len(rest) // 4gepa_train, gepa_val = rest[:-val_size], rest[-val_size:]
optimizer = dspy.GEPA( metric=gepa_metric, reflection_lm=dspy.LM("openai/gpt-5.4", temperature=1.0, max_tokens=32000), auto="light", num_threads=4,)tuned_gepa = optimizer.compile(agent, trainset=gepa_train, valset=gepa_val)print("after GEPA:", evaluate(tuned_gepa).score)Як це виглядає наживо, показує наш урізаний прогін на тих самих сорока питаннях: 24 у навчальній вибірці, 8 у валідаційній, бюджет max_metric_calls=200 замість auto="light", а в ролі reflection_lm — та сама Gemma 4 E4B замість сильної хмарної моделі. Прогін перервався на сьомій ітерації, підсумкової оцінки в нього немає, але механіку перші хвилини журналу показують добре:
Iteration 0: Base program full valset score: 0.6875 over 8 / 8 examplesIteration 1: Selected program 0 score: 0.6875Iteration 1: Proposed new text for react: You are an intelligent Customer Service Agent whose sole purpose is to answer customer queries using information exclusively sourced from the shop's Knowledge Base (KB). ...Iteration 1: New subsample score 2.0 is not better than old score 2.5, skippingIteration 2: Selected program 0 score: 0.6875Iteration 2: All subsample scores perfect for parent 0. Skipping.Iteration 3: Selected program 0 score: 0.6875Iteration 3: Proposed new text for extract.predict: You are an expert Customer Service AI agent tasked with answering customer inquiries using only the provided shop Knowledge Base (KB). ...Iteration 3: New subsample score 1.5 is not better than old score 2.0, skippingПочатковий агент набрав на валідації 0,6875: це середня оцінка нашої метрики, у якій довга правильна відповідь коштує 0,5. На першій ітерації модель-рефлектор переписала інструкцію кроку react. На тих самих трьох прикладах новий кандидат набрав у сумі 2,0 проти попередніх 2,5, і GEPA його викинув, не витрачаючи перевірку на валідаційній вибірці. На другій ітерації всі три взяті приклади вже були розв'язані ідеально, вчитися не було на чому, і GEPA пропустив хід. До зупинки він чотири рази запропонував нову інструкцію, по два рази для кожного предиктора, і жодна не пройшла перевірку на трьох прикладах. Так GEPA і береже бюджет: дорогу перевірку на всій валідаційній вибірці проходять лише кандидати, які вже показали себе на маленькій пачці. Багато залежить і від моделі-рефлектора. У нас її роль грала та сама маленька Gemma, і жодна з її інструкцій не виявилася кращою за початкову. Документація недарма радить брати для цієї ролі сильну модель.
У GEPA теж є auto="light", і бюджет він друкує на початку роботи: «approx N metric calls of the program». Попри назву, це запуски програми, по одному на кожен перевірений приклад. Для нашого агента і трьохсот прикладів, розбитих як у коді вище (60 тестових, 180 навчальних, 60 валідаційних), це близько 1 090 запусків. Саму функцію метрики він викликає частіше, близько 1 550 разів: для відгуку щодо окремого предиктора — вдруге, і в бюджет ці виклики не входять. Замість auto бюджет можна задати прямо: max_metric_calls — у тих самих запусках програми, max_full_evals — кількістю повних проходів по вибірках.
Що варто знати про GEPA перед запуском:
reflection_lmобов'язковий. З версії 3.4.1 це має бути модель DSPy, яка вміє відповідати JSON. Документація радить сильну модель: її викликають рідко, по кілька десятків разів за прогін.- GEPA досі позначено як експериментальний, а на Python 3.15 він не встановлюється.
- Приклади в промпті GEPA не чіпає. Якщо потрібні й вони, GEPA поєднують із
BootstrapFewShotчерезBetterTogether. - Якщо вказати
log_dir, GEPA зберігає туди всіх кандидатів і може продовжити перерваний прогін з того самого місця.
Як дізнатися, скільки витрачено
DSPy уміє рахувати токени. Облік вмикається на час виклику через dspy.context:
with dspy.context(track_usage=True): result = agent(question="Do you ship to Canada?")
print(result.get_lm_usage()) # {'openai/google/gemma-4-e4b': {'prompt_tokens': 2019, 'completion_tokens': 605, ...}}Агент зробив три виклики моделі: 2 019 токенів пішло в запитах і 605 прийшло у відповідях. 351 із цих 605 — приховані міркування: Gemma 4 спершу думає сама із собою і лише потім відповідає, тому кожен її крок помітно повільніший, ніж можна чекати від такої короткої відповіді. Відповіді з кешу в облік не потрапляють: якщо це питання вже ставили, словник виявиться порожнім.
Цифри збираються по кожній моделі окремо. Якщо модель хмарна, ціна кожного виклику лежить в історії моделі, у lm.history. Докладний хід оптимізації — кандидатів, оцінки, промпти — можна надсилати в MLflow: mlflow.dspy.autolog(log_compiles=True, log_evals=True, log_traces_from_compile=True) перед запуском. Викликаний без аргументів, він не запише ні саму оптимізацію, ні результати оцінок: ці три прапорці за замовчуванням вимкнені.
Результат
Як зберегти і завантажити налаштованого агента
tuned.save("agent.json") записує те, що дібрав оптимізатор: інструкції та приклади кожного предиктора, плюс версії Python і DSPy, на яких ішло налаштування. Код програми у файл не потрапляє. Тому під час завантаження агента спершу створюють так само, як під час налаштування, а потім накладають на нього збережений стан:
agent = dspy.ReAct(AnswerFromKb, tools=[search_kb], max_iters=5)agent.load("agent.json")print(agent(question="How long is the refund period?").answer) # 30 daysФайл маленький, читається очима, і його зручно зберігати в репозиторії поруч із кодом: зміни інструкцій видно у звичайному diff. Ключів API в ньому немає ніколи. Адреси серверів DSPy під час завантаження теж відкидає, якщо явно не передати allow_unsafe_lm_state=True. Модель, на якій агент працюватиме, задають як завжди, через dspy.configure. Якщо файл збережено іншою версією DSPy, під час завантаження з'явиться попередження, але агент завантажиться.
Якщо на боці, який завантажує агента, немає вашого коду, є другий спосіб: tuned.save("agent/", save_program=True) зберігає програму цілком через cloudpickle, а dspy.load("agent/", allow_pickle=True) відновлює її. Без вашого коду це працює лише для класів, оголошених у самому скрипті, що зберігає: їх cloudpickle зберігає повністю, а для класу з імпортованого модуля — лише посилання, і завантаження без цього модуля падає з ModuleNotFoundError. Якщо сигнатура й інструменти лежать у вашому модулі, перелічіть його під час збереження: tuned.save("agent/", save_program=True, modules_to_serialize=[my_module]). Такий файл містить виконуваний код, тому завантажувати його можна лише з довіреного джерела.
Як подивитися, що змінив оптимізатор
Інструкції та приклади кожного предиктора доступні прямо з коду:
for name, predictor in tuned.named_predictors(): print(name, "| demos:", len(predictor.demos)) print(predictor.signature.instructions)Ось що вийшло в нашому прогоні MIPROv2 (довгі місця пропущено):
react | demos: 4You are a highly specialized AI Agent Planner (Reasoning Engine). Your sole function is to analyze a customer's question and the entire conversation history (`trajectory`) accumulated so far to determine the single, most logical next step needed to find the answer using only the available tools....**Tool Definitions:**1. **`search_kb`**: Use this when you need to actively retrieve new information from the knowledge base. The argument must be a specific, focused search query (e.g., `'return period'`). Do not use general terms; focus on the core concepts of the question or observations.2. **`finish`**: Use this only when your reasoning confirms that you have gathered sufficient evidence across all parts of the trajectory to formulate a definitive answer, and no further tool calls are required....extract.predict | demos: 4You are a sophisticated AI knowledge synthesis engine responsible for compiling the final answer to a customer query based *exclusively* on an agent's complete investigative history (the 'trajectory'). ......2. **Answer (Final Output):** * Provide a final answer that is extremely concise, direct, and factual. * The `answer` must directly address the initial `Question`. * Do not include explanations, filler words, or unnecessary introductory phrases in the final `answer`. ...Інструкції писала модель, і це помітно: вони довгі, із заголовками й повторами. Зате в інструкції кроку extract прямо сказано, що відповідь має бути гранично короткою і без вступів, — саме те, за що метрика знімала бали.
Зверніть увагу на крок react. Його початкова інструкція містила перелік інструментів, який ReAct зібрав із коду: назви, рядки документації, схеми аргументів. Оптимізатор переписав інструкцію цілком, і тепер інструменти описано його словами. Агент працює, але якщо додати в код новий інструмент або перейменувати аргумент, збережена інструкція про це не дізнається, і налаштування доведеться повторити.
Те саме лежить в agent.json. Корисно читати це після кожного налаштування. Оптимізатор підганяє промпт під метрику, а не під ваші наміри: якщо метрика десь помиляється, це насамперед проявиться в інструкції.
Коли запускати оптимізацію заново
Налаштування прив'язане до моделі, даних і коду. Його запускають знову, коли:
- змінилася модель або її версія в провайдера;
- змінилися інструменти, сигнатура або будова програми;
- у базі знань чи в питаннях користувачів з'явилося щось, чого не було в даних;
- оновився DSPy так, що змінилися предиктори, як буде з
ReActу 3.5.
Щоразу порівнюють оцінку на тестовій вибірці до і після. Якщо нова модель після налаштування не краща за стару, переходити на неї не потрібно: це рішення теж ухвалюють за цифрами, а не за враженням.
Що ще є в DSPy
За межами прикладу лишилося багато корисного:
dspy.Refineіdspy.BestOfNзапускають модуль кілька разів і обирають відповідь, яка найкраще пройшла перевірку.dspy.RLM— модуль для завдань із величезним контекстом. Дані лежать змінними в інтерпретаторі Python, а модель пише код, щоб їх переглядати, і сама викликає модель на потрібних шматках. Він замінюєCodeActіProgramOfThought, їх приберуть у 3.5.- Модулі можна викликати асинхронно через
acall, отримувати відповідь шматками черезdspy.streamifyі підключати інструменти із серверів MCP черезdspy.Tool.from_mcp_tool. - Модулі складаються в програми, як шари в PyTorch: свій клас, нащадок
dspy.Module, викликає уforwardкілька модулів, і оптимізатор налаштовує їх усі одразу.
Коли DSPy не потрібен
DSPy окуповується, коли завдання повторюється, його можна виміряти і модель змінюватиметься. Він зайвий, якщо:
- немає прикладів із правильними відповідями і способу оцінити відповідь. Без них лишається тільки зручний запис викликів, а головне — оптимізація — недоступне;
- завдання разове або промпт і так працює;
- текст промпту має бути точно таким, як його написала людина, наприклад через юридичні формулювання;
- потрібен повний контроль над кожним токеном запиту: промпт, який збирає адаптер, довший і шаблонніший за ручний.
Обмеження варто пам'ятати і тоді, коли DSPy підходить. Промпт, налаштований під одну модель, на іншу не переноситься. На маленькому наборі даних оптимізатор перенавчається, і без окремої тестової вибірки цього не видно. API змінюється від версії до версії, тому версію DSPy закріплюють у залежностях, а після оновлення запускають оцінку заново.