# Как ускорить Python-код с помощью ИИ-агента: профилирование и переписывание горячих 5%

> AI Release · @ai_release1 · https://ai-release.org/guides/kak-uskorit-python-kod-s-pomoschyu-ii-agenta-profilirov.html

## TL;DR
- Время выполнения: 40–60 минут на первый проход (профиль + одна правка + проверка)
- Уровень сложности: Intermediate
- Понадобится: Python 3.9+ (`cProfile`, `pstats` — входят в стандартную библиотеку), `py-spy`, `line_profiler`, `pytest`, доступ ИИ-агента к репозиторию (модель и версия агента — сверьтесь с документацией вашего инструмента), тесты проекта, если они есть

## Что вы получите
- Файл `profile.out` и текстовый отчёт профиля, где явно виден список функций, съедающих основное время, с числами `tottime`/`cumtime`.
- Переписанную одну функцию из «горячего» топа (не больше 5% строк проекта) с diff-ом, зелёными тестами и таблицей замеров «до/после» в миллисекундах.
- Готовый промпт-контракт для агента, который запрещает ему переписывать весь файл и выдумывать цифры.

## Быстрый старт
```bash
python -m venv .venv && source .venv/bin/activate && python -m pip install -U pip py-spy line_profiler pytest
python -m cProfile -o profile.out main.py
python -c "import pstats; pstats.Stats('profile.out').sort_stats('tottime').print_stats(15)"
py-spy record -o profile.svg -- python main.py
```

Подробности и проверка — в шагах ниже.

## Промпт для копирования
![Иллюстрация к разделу «Промпт для копирования»](https://ai-release.org/guides/img/kak-uskorit-python-kod-s-pomoschyu-ii-agenta-profilirov-ru-1.jpg?v=1795337769)

```prompt
Роль: ты — инженер по производительности Python. Ты работаешь в моём репозитории <путь-к-репозиторию> и не меняешь файлы за пределами списка, который я дам.

Контекст:
- Проект: <краткое описание проекта в 2–3 строках>.
- Целевая функция: <модуль.функция> в файле <путь/к/файлу.py>.
- Профиль: файл profile.out (cProfile, сортировка по tottime) и вывод line_profiler по этой функции.
- Бюджет времени: <целевое время на один вызов, мс>.
- Ограничения: Python <версия>, новые зависимости добавлять нельзя, публичную сигнатуру функции не менять, поведение при исключениях и граничные случаи сохранить.

Задача:
1. Прочитай профиль и назови три самых дорогих участка по tottime, приведя числа из профиля.
2. Для самого дорогого участка предложи не больше трёх вариантов переписывания, от простого к рискованному: (а) убрать лишнюю работу внутри цикла, (б) заменить структуру данных, (в) векторизовать через библиотеку, которая уже есть в зависимостях.
3. Для каждого варианта укажи: что меняется, ожидаемый эффект, риск изменения поведения, как проверить эквивалентность.
4. Реализуй только тот вариант, который я подтвержу словом «делай». До подтверждения файлы не редактируй.
5. После правки покажи diff, запусти <команда тестов> и <команда бенчмарка>, приведи время «до» и «после» в одной таблице.
6. Если тесты падают — откати правку и объясни причину.

Формат ответа: таблица «участок | tottime | что делаем | риск», затем diff, затем результат тестов, затем таблица замеров.
Не добавляй зависимости, не переписывай файл целиком, не трогай форматирование несвязанных строк, не выдумывай цифры — бери только из вывода команд.
```

Заменяемые места: `<путь-к-репозиторию>`, `<краткое описание проекта>`, `<модуль.функция>`, `<путь/к/файлу.py>`, `<целевое время, мс>`, `<версия Python>`, `<команда тестов>`, `<команда бенчмарка>`.

## Требования и подготовка
![Иллюстрация к разделу «Требования и подготовка»](https://ai-release.org/guides/img/kak-uskorit-python-kod-s-pomoschyu-ii-agenta-profilirov-ru-2.jpg?v=1795337775)

- ОС: Linux/macOS (в примерах `bash`) или Windows 10/11 с PowerShell — команды профилирования одинаковые, отличается только активация venv: `.venv\Scripts\Activate.ps1`.
- Python 3.9+ и рабочий `venv`. Минимальную версию для ваших пакетов сверьте с документацией проекта.
- Права на запись в каталог проекта: профиль пишется в `profile.out` в текущей папке.
- Тесты: если в проекте есть `pytest`, прогоните их до правок и зафиксируйте, что они зелёные. Это база для сравнения.

| Инструмент | Зачем | Команда проверки |
|---|---|---|
| `cProfile` / `pstats` | Профиль по функциям: `tottime` — время в самой функции, `cumtime` — с учётом вложенных вызовов | `python -c "import cProfile, pstats; print('ok')"` |
| `py-spy` | Сэмплирующий профилировщик, строит SVG-флеймграф без правок кода | `py-spy --version` |
| `line_profiler` | Профиль по строкам внутри одной функции | `python -c "import line_profiler; print('ok')"` |
| `pytest` | Проверка, что переписанная функция ведёт себя так же | `pytest -q` |

**Пример:** успешная проверка выглядит так — `py-spy --version` печатает строку вида `py-spy 0.x.x` (конкретную версию сверьте с документацией), `pytest -q` печатает `12 passed`.

Почему это работает: профилировщики не угадывают, а измеряют фактическое время выполнения, поэтому «горячие» функции видны по числам, а не по интуиции.

## Шаг 1. Профилирование: найти горячие 5%
**Что сделать:** запустите скрипт под `cProfile`, затем отсортируйте отчёт по `tottime` и выпишите топ-5 функций. Для одной функции снимите построчный профиль.

```bash
python -m cProfile -o profile.out main.py
python -c "import pstats; pstats.Stats('profile.out').sort_stats('tottime').print_stats(15)"
```

Фрагмент ожидаемого вывода (числа у вас будут свои):

```
   ncalls  tottime  percall  cumtime  percall filename:lineno(function)
     1200    4.812    0.004    4.812    0.004 app/hot.py:14(process_rows)
     1200    0.731    0.001    0.731    0.001 app/parse.py:7(normalize)
```

Построчный профиль одной функции:

```bash
kernprof -l -v main.py
```

В коде целевой функции перед запуском поставьте декоратор `@profile` (его добавляет `line_profiler`; после замеров декоратор уберите, иначе получите `NameError: name 'profile' is not defined` при обычном запуске).

**Зачем:** правило «горячих 5%» означает, что правим только функцию из вершины профиля, а не весь проект. Такой правкой вы затрагиваете малую долю кода, но получаете эффект на всём времени выполнения.

**Как проверить:** в отчёте `print_stats(15)` первая строка по `tottime` — функция из вашего кода (не `built-in method`), и её `tottime` заметно больше остальных. Дополнительно можно посмотреть флеймграф: `py-spy record -o profile.svg -- python main.py` — файл `profile.svg` открывается в браузере и показывает широкие блоки самых «толстых» вызовов.

Структуру папок и правила, которые делают поведение агента предсказуемым, разберите заранее: [ICM на практике: структура папок, которая делает ИИ-агента управляемым](https://ai-release.org/guides/icm-praktika-struktura-papok-agenta.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

## Шаг 2. Переписывание горячей функции агентом
**Что сделать:** передайте агенту профиль и ограничения из промпта выше, дождитесь таблицы вариантов, подтвердите один и получите diff.

Порядок работы:

1. Откройте чат/сессию агента в каталоге проекта и вставьте промпт, подставив реальные пути.
2. Приложите вывод `print_stats(15)` текстом — агент должен ссылаться на числа из него.
3. Выберите вариант с наименьшим риском (обычно «убрать лишнюю работу внутри цикла»).
4. Напишите `делай` и дождитесь diff-а. Проверьте, что изменён только целевой файл.

**Пример:** агент предложил три варианта и вы выбрали второй — заменить повторный поиск в списке внутри цикла на множество (`set`). Diff выглядит так:

```diff
-    for row in rows:
-        if row.key in keys_list:
+    keys = set(keys_list)
+    for row in rows:
+        if row.key in keys:
```

**Зачем:** ограничение «одна функция, не более 5% строк, без новых зависимостей» не даёт агенту переписать половину проекта и сломать поведение, которое вы не проверяете.

**Как проверить:** `git diff --stat` показывает изменения только в одном файле, например `app/hot.py | 12 ++++++------`. Если в diff-е появились `requirements.txt`, `pyproject.toml` или десятки файлов — откатывайте: `git checkout -- .`.

Как такой агент устроен и чем отличается от обычного чата, разобрано здесь: [Как превратить обычный чат с LLM в полноценного AI-агента](https://ai-release.org/guides/kak-prevratit-obychnyy-chat-s-llm-v-polnotsennogo-ai-ag.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

## Шаг 3. Проверка результата: тесты и замер
![Иллюстрация к разделу «Шаг 3. Проверка результата: тесты и замер»](https://ai-release.org/guides/img/kak-uskorit-python-kod-s-pomoschyu-ii-agenta-profilirov-ru-3.jpg?v=1795337780)

**Что сделать:** прогоните тесты и снимите замер «до/после» одним и тем же скриптом.

```python
import time, statistics
from app.hot import process_rows   # <ваш-модуль>

def bench(fn, arg, n=5):
    times = []
    for _ in range(n):
        t = time.perf_counter()
        fn(arg)
        times.append((time.perf_counter() - t) * 1000)
    return min(times), statistics.median(times)

print("min/median, ms:", bench(process_rows, data))
```

Запустите скрипт дважды: на исходной версии (до `git apply`) и на переписанной, результаты внесите в таблицу.

| Версия `process_rows` | min, мс | median, мс | Тесты |
|---|---|---|---|
| до правки | `<ваш замер>` | `<ваш замер>` | `passed` |
| после правки | `<ваш замер>` | `<ваш замер>` | `passed` |

**Зачем:** ускорение без проверки эквивалентности — это изменённое поведение, а не оптимизация. Сравнение min и median отсекает случайные выбросы от прогрева и фоновой нагрузки.

**Как проверить:** чек-лист приёмки.

- [ ] `pytest -q` завершился кодом 0 и печатает `passed`
- [ ] `git diff` меняет только согласованную функцию
- [ ] `median` после правки меньше `median` до правки
- [ ] в `requirements.txt` не появилось новых строк
- [ ] декоратор `@profile` удалён из кода перед коммитом

Почему это работает: `time.perf_counter()` даёт монотонные часы высокого разрешения, поэтому разница в миллисекундах отражает реальное изменение, а не сдвиг системного времени.

## Возможные проблемы и решения

**Проблема. `pip install py-spy` падает на системном Python**
- Ошибка: `error: externally-managed-environment`
- Причина: в Debian/Ubuntu новые версии Python блокируют установку пакетов в системное окружение (механизм PEP 668).
- Решение: не ставьте пакеты глобально — активируйте venv и повторите:
```bash
python -m venv .venv && source .venv/bin/activate
python -m pip install py-spy
```
Проверка: `py-spy --version` печатает версию без ошибки.

**Проблема. После правки агента тесты падают на размерах массивов**
- Ошибка: `ValueError: operands could not be broadcast together with shapes (1000000,) (999999,)`
- Причина: при переписывании цикла на векторную операцию агент изменил границу среза или длину результата на единицу.
- Решение: откатите правку и попросите агента сохранить длину результата, приложив падающий тест:
```bash
git checkout -- app/hot.py
pytest -q tests/test_hot.py::test_length
```
Затем в промпте допишите строку: «Результат функции должен иметь ту же длину, что и вход; приложи проверку `len(out) == len(rows)`».

**Проблема. Тесты падают на сравнении дробных чисел**
- Ошибка: `assert 0.30000000000000004 == 0.3`
- Причина: перестановка операций сложения float изменила порядок округления — поведение формально другое.
- Решение: в тесте сравнивайте с допуском `pytest.approx`, а в коде сохраняйте прежний порядок суммирования:
```python
import pytest
assert result == pytest.approx(0.3, rel=1e-9)
```
Если бизнес-логика требует точности — верните исходную формулу и попросите агента оптимизировать другой участок.

## Резюме и следующие шаги
Вы получили профиль с числами, одну переписанную горячую функцию и таблицу замеров «до/после» с зелёными тестами. Следующий проход — повторить шаги 1–3 для второй функции из топа профиля, начиная с нового замера.

## FAQ
**Сколько функций можно переписывать за один проход?**
Одну. Правило «горячих 5%» работает только при малом diff-е: так вы можете проверить каждое изменение тестами и откатить его одной командой `git checkout`.

**Обязательно ли ставить `py-spy`, если есть `cProfile`?**
Нет. `cProfile` входит в стандартную библиотеку и уже даёт список функций с `tottime`. `py-spy` нужен, когда хочется увидеть флеймграф или снять профиль без правок кода; минимальную версию и права запуска сверьтесь с документацией.

**Что делать, если после правки стало медленнее?**
Откатите изменение (`git checkout -- <файл>`), вернитесь к отчёту профиля и выберите другой участок — например, функцию со вторым по величине `tottime`. Замеры min и median при повторном прогоне покажут, был ли эффект реальным.

**Можно ли доверять цифрам ускорения, которые называет агент?**
Только если они взяты из вывода ваших команд. В промпте прямо запрещено выдумывать числа; сравнивайте замеры, снятые вашим скриптом бенчмарка на одной и той же машине.
