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 закрепляют в зависимостях, а после обновления запускают оценку заново.