Инструменты

Зачем Go-разработчику Python

Зачем Java-разработчику Python

Прод-сервис вокруг LLM вполне можно и стоит писать на Java: вызов API, стриминг, лимиты, очереди, RAG на pgvector — всё это Spring Boot делает отлично, у Anthropic есть официальный Java SDK, а поверх него — LangChain4j и Spring AI. Но часть работы живёт в Python, и притворяться, что её нет, дорого:

Прод-сервис вокруг LLM вполне можно и стоит писать на Go: вызов API, стриминг, лимиты, очереди, RAG на pgvector — всё это Go делает отлично, и у Anthropic есть официальный Go SDK. Но часть работы живёт в Python, и притворяться, что её нет, дорого:

• Evals и анализ. Разметка, подсчёт метрик по срезам, сравнение версий промпта, графики. pandas и Jupyter здесь стандарт, и коллеги-ML будут ждать от вас .ipynb или скрипт, а не Go-бинарьjar.
• Новые возможности приходят в Python SDK первыми или одновременно с TypeScript; примеры в документации провайдеров — в первую очередь на Python.
• Экосистема: fine-tuning (модуль 10), эмбеддинг-модели и rerankers локально, парсинг PDF, токенизаторы, фреймворки для агентов и RAG.
• Собеседования. Live-coding на AI engineer часто на Python: «напиши функцию, которая вызывает модель и парсит ответ», «посчитай precision по этому DataFrame».

Рабочая стратегия: сервисы на Java и Spring, эксперименты, evals и анализ — на Python. Цель модуля — чтобы Python не тормозил вас: читать чужой код, писать скрипты и небольшие сервисы идиоматично, знать, где подвохи для человека с Java-рефлексами: типы, которые никто не проверяет без тайпчекера, исключения без throws в сигнатуре, кооперативная конкурентность вместо потоков и упаковка без Maven.

Рабочая стратегия: сервисы на Go, эксперименты, evals и анализ — на Python. Цель модуля — чтобы Python не тормозил вас: читать чужой код, писать скрипты и небольшие сервисы идиоматично, знать, где подвохи для человека с Go-рефлексами.

Шпаргалка Go ↔ Python

Шпаргалка Java ↔ Python

Фильтруйте по разделу или ищите по слову. Колонка «Подвох» — то, на чём спотыкаются именно GoJava-разработчики.

Модули и пакеты

В Java пакет — это пространство имён и директория, а единица сборки — Maven-модуль с pom.xml. В Python модуль = файл .py, пакет = директория (исторически с __init__.py), а «проект» описывается pyproject.toml. Импорты разрешаются через sys.path — аналог classpath, но собранный в рантайме из текущей директории и окружения, а не из описания сборки. Отсюда классическая боль — «работает из корня, не работает из поддиректории». Лечится src-layout и установкой проекта в окружение в editable-режиме (uv делает это сам). Модификаторов доступа нет: _name — «приватное» по соглашению, но доступно всем, и компилятор этого не проверит.

В Go пакет = директория, модуль = go.mod. В Python модуль = файл .py, пакет = директория (исторически с __init__.py), а «проект» описывается pyproject.toml. Импорты разрешаются через sys.path, а не через путь модуля, поэтому классическая боль — «работает из корня, не работает из поддиректории». Лечится src-layout и установкой проекта в окружение в editable-режиме (uv делает это сам). Экспорт не по регистру, а по соглашению: _name — «приватное», но доступно всем.

Типы и dataclass vs struct

Типы: dataclass и pydantic vs records

Python динамически типизирован: аннотации (def f(x: int) -> str) интерпретатор не проверяет, они ближе к Javadoc, чем к javac. Проверку делает внешний тайпчекер (mypy, pyright), и в команде с Java-культурой его стоит включить в CI в строгом режиме, иначе ошибки, которые у вас ловит компилятор, всплывут в рантайме. @dataclass(frozen=True) — ближайший аналог record: поля, конструктор, __eq__, __hash__, __repr__. Но он не валидирует значения: User(age="десять") создастся спокойно, а в Java не скомпилировалось бы. Для данных с границы доверия (JSON от клиента, ответ модели) нужен pydantic: это record, Jackson и Bean Validation в одной библиотеке.

Python динамически типизирован, аннотации (def f(x: int) -> str) интерпретатор не проверяет. Проверку делает внешний тайпчекер (mypy, pyright), и в команде с Go-культурой его стоит включить в CI со строгим режимом. @dataclass — ближайший аналог struct: поля, конструктор, сравнение. Но он не валидирует значения: User(age="десять") создастся спокойно. Для данных с границы доверия (JSON от клиента, ответ модели) нужен pydantic.

Исключения vs error

Исключения: все unchecked

Исключения Java-разработчику привычны, но в Python все они unchecked: сигнатура функции не говорит, что она бросает, и никто не заставит обработать ошибку. Правила те же, что в хорошем Java-коде: ловить конкретные классы (except anthropic.RateLimitError), а не голый except Exception; не глотать молча; оборачивать с сохранением причины: raise MyError("…") from e (аналог new MyException("…", e), цепочка видна в traceback, как Caused by:). Ресурсы закрывает with (context manager) — это try-with-resources, а __enter__/__exit__ — аналог AutoCloseable.

Нет if err != nil, ошибки летят исключениями вверх по стеку, пока их не поймают. Для Go-разработчика это ощущается как паника, которую принято ловить. Правила хорошего тона: ловить конкретные классы (except anthropic.RateLimitError), а не голый except Exception; не глотать молча; оборачивать с сохранением причины: raise MyError("…") from e (аналог fmt.Errorf("…: %w", err), цепочка видна в traceback). Ресурсы закрывает with (context manager) — это defer, привязанный к блоку, а не к функции.

Окружение: uv, venv, pyproject

Главная боль Python для Java-разработчика — окружения. В Maven зависимости лежат в общем ~/.m2, но classpath у каждого проекта свой и собирается из pom.xml, а результат — самодостаточный jar. В Python пакеты ставятся в интерпретатор, поэтому на каждый проект нужен venv (virtual environment — отдельная директория с копией/ссылкой на интерпретатор и своими site-packages). Исторический зоопарк: pip, virtualenv, pip-tools, poetry, pipenv, conda, pyenv. В 2026 году разумный дефолт один — uv от Astral: менеджер версий Python (как SDKMAN), venv, зависимостей и lock-файла (как Maven) в одном быстром бинаре (он написан на Rust).

Главная боль Python для гоферов — окружения. В Go зависимости изолированы модулем и собираются в бинарь. В Python пакеты ставятся в интерпретатор, поэтому на каждый проект нужен venv (virtual environment — отдельная директория с копией/ссылкой на интерпретатор и своими site-packages). Исторический зоопарк: pip, virtualenv, pip-tools, poetry, pipenv, conda, pyenv. В 2026 году разумный дефолт один — uv от Astral: менеджер версий Python, venv, зависимостей и lock-файла в одном быстром бинаре (он написан на Rust).

async/await vs goroutines

async/await vs virtual threads

Самое важное концептуальное различие. В Java 21 конкурентность снова прозрачна: любой блокирующий код можно запустить в виртуальном потоке, JVM сама снимает его с потока-носителя на блокирующем I/O, а потоки реально работают параллельно на всех ядрах. Ближайший Java-аналог asyncio — реактивный стек (WebFlux, Reactor): Mono/Flux так же «заражают» сигнатуры, а блокирующий вызов внутри так же ломает всё. В Python asyncio — кооперативная многозадачность в одном потоке:

Самое важное концептуальное различие. В Go конкурентность прозрачна: любая функция может быть запущена в горутине, рантайм сам переключает их на блокирующих вызовах, горутины реально работают параллельно на всех ядрах. В Python asyncio — кооперативная многозадачность в одном потоке:

• Функция должна быть объявлена async def, и вызывать её нужно через await. Это «окрашивание функций»: async заражает весь стек вызовов вверх.
• Переключение происходит только в точках await. Синхронный блокирующий вызов внутри корутины (requests.get, time.sleep, синхронный клиент БД, тяжёлый CPU-код) останавливает весь event loop: все остальные запросы сервиса ждут. Это самая частая прод-ошибка в FastAPI-сервисах.
• Параллелизма на CPU нет из-за GIL (Global Interpreter Lock). Для I/O-bound LLM-вызовов это не важно: тысячи одновременных запросов в одном потоке — нормально. Для CPU-задач — процессы (ProcessPoolExecutor) или нативные библиотеки (numpy, pandas отпускают GIL внутри). Free-threaded сборка CPython без GIL существует с 3.13, но экосистема к ней ещё привыкает.
• Вместо BlockingQueue — asyncio.Queue. Отмена — task.cancel(), которое бросает CancelledError в точке await (похоже на interrupt() и InterruptedException, только срабатывает исключительно на await); таймаут — asyncio.timeout().
• Каналов как примитива языка нет; есть asyncio.Queue. Отмена — не context, а task.cancel(), которое бросает CancelledError в точке await; таймаут — asyncio.timeout().

import asyncio
import anthropic

client = anthropic.AsyncAnthropic()  # у SDK есть sync и async клиенты — в async-коде только async

async def classify(ticket: str) -> str:
    resp = await client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=16,
        system="Ответь одним словом: billing, tech, refund или other.",
        messages=[{"role": "user", "content": ticket}],
    )
    return resp.content[0].text.strip()

async def main(tickets: list[str]) -> list[str | BaseException]:
    sem = asyncio.Semaphore(10)

    async def guarded(t: str) -> str:
        async with sem:
            return await classify(t)

    # gather(return_exceptions=True) ≈ invokeAll без fail-fast: ошибки возвращаются значениями
    return await asyncio.gather(*(guarded(t) for t in tickets), return_exceptions=True)

# Ошибка, которую ловят на ревью:
async def bad_handler() -> None:
    import time
    time.sleep(2)             # блокирует ВЕСЬ event loop на 2 с
    await asyncio.sleep(2)    # правильно: отдаёт управление другим задачам
    # синхронную библиотеку без async-версии — в поток:
    # result = await asyncio.to_thread(sync_call, arg)

if __name__ == "__main__":
    print(asyncio.run(main(["Не прошла оплата картой", "Приложение падает при входе"])))

import asyncio
import anthropic

client = anthropic.AsyncAnthropic()  # у SDK есть sync и async клиенты — в async-коде только async

async def classify(ticket: str) -> str:
    resp = await client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=16,
        system="Ответь одним словом: billing, tech, refund или other.",
        messages=[{"role": "user", "content": ticket}],
    )
    return resp.content[0].text.strip()

async def main(tickets: list[str]) -> list[str | BaseException]:
    sem = asyncio.Semaphore(10)

    async def guarded(t: str) -> str:
        async with sem:
            return await classify(t)

    # gather(return_exceptions=True) ≈ errgroup без fail-fast: ошибки возвращаются значениями
    return await asyncio.gather(*(guarded(t) for t in tickets), return_exceptions=True)

# Ошибка, которую ловят на ревью:
async def bad_handler() -> None:
    import time
    time.sleep(2)             # блокирует ВЕСЬ event loop на 2 с
    await asyncio.sleep(2)    # правильно: отдаёт управление другим задачам
    # синхронную библиотеку без async-версии — в поток:
    # result = await asyncio.to_thread(sync_call, arg)

if __name__ == "__main__":
    print(asyncio.run(main(["Не прошла оплата картой", "Приложение падает при входе"])))

// То же на Java 21: никакой «окраски» функций, блокирующий вызов блокирует только свой виртуальный поток.
record Outcome(String label, Throwable error) {}

static List<Outcome> classifyAll(AnthropicClient client, List<String> tickets) {
    var sem = new Semaphore(10);
    List<Future<String>> futures;
    try (var exec = Executors.newVirtualThreadPerTaskExecutor()) { // close() ждёт все задачи
        futures = tickets.stream().map(t -> exec.submit(() -> {
            sem.acquire();
            try {
                Message resp = client.messages().create(MessageCreateParams.builder()
                        .model("claude-haiku-4-5")
                        .maxTokens(16)
                        .system("Ответь одним словом: billing, tech, refund или other.")
                        .addUserMessage(t)
                        .build());
                return resp.content().stream()
                        .flatMap(b -> b.text().stream())
                        .map(tb -> tb.text().strip())
                        .collect(Collectors.joining());
            } finally {
                sem.release();
            }
        })).toList();
    }
    // Без fail-fast, как gather(return_exceptions=True): ошибка — значение в списке.
    return futures.stream()
            .map(f -> f.state() == Future.State.SUCCESS
                    ? new Outcome(f.resultNow(), null)
                    : new Outcome(null, f.exceptionNow()))
            .toList();
}

// То же на Go: никакой «окраски» функций, блокирующий вызов блокирует только свою горутину.
func classifyAll(ctx context.Context, client *anthropic.Client, tickets []string) ([]string, []error) {
	out := make([]string, len(tickets))
	errs := make([]error, len(tickets))
	var g errgroup.Group
	g.SetLimit(10)
	for i, t := range tickets {
		g.Go(func() error {
			resp, err := client.Messages.New(ctx, anthropic.MessageNewParams{
				Model:     "claude-haiku-4-5",
				MaxTokens: 16,
				System:    []anthropic.TextBlockParam{{Text: "Ответь одним словом: billing, tech, refund или other."}},
				Messages:  []anthropic.MessageParam{anthropic.NewUserMessage(anthropic.NewTextBlock(t))},
			})
			if err != nil {
				errs[i] = err // без fail-fast, как gather(return_exceptions=True)
				return nil
			}
			for _, b := range resp.Content {
				if tb, ok := b.AsAny().(anthropic.TextBlock); ok {
					out[i] = strings.TrimSpace(tb.Text)
				}
			}
			return nil
		})
	}
	_ = g.Wait()
	return out, errs
}

Pydantic: типы на границе доверия

Pydantic — библиотека моделей данных с валидацией в рантайме. Для AI engineering это центральный инструмент: FastAPI строит на нём валидацию запросов и OpenAPI, а для LLM он делает три вещи — описывает схему ожидаемого ответа, генерирует из неё JSON Schema для structured outputs и валидирует то, что модель вернула. В Go ближайший аналог — struct с тегами json + validate плюс генерация схемы через invopop/jsonschema; в Python это одна библиотека.В Java ближайший аналог — record + Jackson + Bean Validation (@Size, @Min) плюс генерация схемы через victools jsonschema-generator; в Python это одна библиотека.

from typing import Literal
import anthropic
from pydantic import BaseModel, Field, ValidationError

class TicketTriage(BaseModel):
    category: Literal["billing", "tech", "refund", "other"]
    urgency: int = Field(ge=1, le=5, description="1 — не срочно, 5 — всё горит")
    summary: str = Field(max_length=200)
    needs_human: bool

client = anthropic.Anthropic()

def triage(ticket: str) -> TicketTriage:
    resp = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": f"Разбери тикет поддержки:\n\n{ticket}"}],
        # structured outputs: модель обязана вернуть JSON по схеме.
        # В старых версиях SDK параметр передаётся через extra_body={"output_config": ...}
        output_config={"format": {"type": "json_schema", "schema": TicketTriage.model_json_schema()}},
    )
    if resp.stop_reason == "max_tokens":
        raise RuntimeError("ответ обрезан, JSON неполный")
    raw = "".join(b.text for b in resp.content if b.type == "text")
    try:
        # схему гарантирует API, но бизнес-ограничения (ge/le, max_length) проверяем сами
        return TicketTriage.model_validate_json(raw)
    except ValidationError as e:
        raise ValueError(f"модель вернула невалидный triage: {e.error_count()} ошибок") from e

Скрипты для экспериментов

Типичный скрипт AI engineer: прочитать набор примеров, прогнать через модель конкурентно, сохранить результаты с метаданными (версия промпта, модель, токены, латентность) для анализа в pandas. Пример ниже самодостаточен: зависимости в PEP 723-заголовке, запуск uv run run_eval.py --prompt v3 cases.jsonl.

# /// script
# requires-python = ">=3.12"
# dependencies = ["anthropic>=0.60", "pandas>=2.2", "pyarrow"]
# ///
import argparse, asyncio, json, time
from pathlib import Path
import anthropic
import pandas as pd

PROMPTS = {
    "v2": "Классифицируй тикет. Ответь одним словом: billing, tech, refund, smalltalk.",
    "v3": Path("prompts/classify_v3.txt").read_text() if Path("prompts/classify_v3.txt").exists() else "",
}
client = anthropic.AsyncAnthropic(max_retries=4)  # ретраи 429/5xx с backoff — встроены в SDK

async def run_case(sem: asyncio.Semaphore, version: str, case: dict) -> dict:
    async with sem:
        t0 = time.perf_counter()
        try:
            resp = await client.messages.create(
                model="claude-haiku-4-5", max_tokens=16, system=PROMPTS[version],
                messages=[{"role": "user", "content": case["text"]}],
            )
            got = resp.content[0].text.strip().lower()
            usage = (resp.usage.input_tokens, resp.usage.output_tokens)
            err = None
        except anthropic.APIError as e:  # не роняем весь прогон из-за одного примера
            got, usage, err = None, (0, 0), type(e).__name__
    return {
        "example_id": case["id"], "category": case["category"], "prompt_version": version,
        "expected": case["label"], "got": got, "passed": int(got == case["label"]),
        "latency_ms": round((time.perf_counter() - t0) * 1000),
        "input_tokens": usage[0], "output_tokens": usage[1], "error": err,
    }

async def main() -> None:
    ap = argparse.ArgumentParser()
    ap.add_argument("cases", type=Path)
    ap.add_argument("--prompt", required=True, choices=PROMPTS)
    ap.add_argument("--concurrency", type=int, default=8)
    args = ap.parse_args()
    cases = [json.loads(line) for line in args.cases.read_text().splitlines() if line.strip()]
    sem = asyncio.Semaphore(args.concurrency)
    rows = await asyncio.gather(*(run_case(sem, args.prompt, c) for c in cases))
    df = pd.DataFrame(rows)
    df.to_parquet(f"results_{args.prompt}_{int(time.time())}.parquet")
    ok = df[df.error.isna()]
    print(f"pass_rate={ok.passed.mean():.3f} n={len(ok)} errors={df.error.notna().sum()}")

if __name__ == "__main__":
    asyncio.run(main())

Обратите внимание: ошибки инфраструктуры (429 после всех ретраев) записываются отдельно и не считаются провалом модели. Смешать их — классическая ошибка, из-за которой «новый промпт стал хуже» в день, когда у провайдера была перегрузка.

FastAPI: сервис-обёртка над LLM

FastAPI — де-факто стандарт для Python-сервисов вокруг моделей: async из коробки, валидация через pydantic, автоматическая OpenAPI-документация. Для Go-разработчика: это net/http + роутер + encoding/json + валидатор + swagger-генератор в одном, с объявлением через аннотации типов. Запускается ASGI-сервером (uvicorn) — это аналог http.Server.Для Java-разработчика: это Spring WebFlux + Jackson + Bean Validation + springdoc-openapi в одном, с маршрутами через декораторы (как @PostMapping) и валидацией по аннотациям типов вместо DI-контейнера и бинов. Запускается ASGI-сервером (uvicorn) — это аналог встроенного Netty или Tomcat.

import json
import anthropic
from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse
from pydantic import BaseModel, Field

app = FastAPI()
client = anthropic.AsyncAnthropic()  # один клиент на процесс: пул соединений переиспользуется

class AskRequest(BaseModel):
    question: str = Field(min_length=1, max_length=8000)  # граница доверия: режем заранее
    max_tokens: int = Field(default=1024, ge=1, le=4096)

def sse(event: str, data: dict) -> str:
    return f"event: {event}\ndata: {json.dumps(data, ensure_ascii=False)}\n\n"

@app.post("/v1/ask/stream")
async def ask_stream(req: AskRequest, request: Request) -> StreamingResponse:
    async def events():
        try:
            async with client.messages.stream(
                model="claude-opus-5",
                max_tokens=req.max_tokens,
                system="Ты ассистент поддержки. Отвечай кратко.",
                messages=[{"role": "user", "content": req.question}],
            ) as stream:
                async for text in stream.text_stream:
                    if await request.is_disconnected():
                        return  # выход из async with закрывает соединение с провайдером
                    yield sse("delta", {"text": text})
                msg = await stream.get_final_message()
            yield sse("done", {
                "stop_reason": msg.stop_reason,
                "input_tokens": msg.usage.input_tokens,
                "output_tokens": msg.usage.output_tokens,
            })
        except anthropic.APIStatusError as e:  # в т.ч. ошибка, пришедшая посреди стрима
            yield sse("error", {"status": e.status_code})

    return StreamingResponse(events(), media_type="text/event-stream",
                             headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"})

@app.get("/healthz")
async def healthz() -> dict:
    return {"ok": True}

# uv run uvicorn app:app --host 0.0.0.0 --port 8000 --workers 2

pandas для анализа evals

pandas — таблицы в памяти (DataFrame) с векторными операциями. Для Go-разработчика это «SQL поверх слайса структур без циклов»:Для Java-разработчика это «SQL поверх List<record> без циклов», как Stream API с Collectors.groupingBy, только короче и векторно: groupby — GROUP BY, merge — JOIN, pivot_table — сводная таблица, query — WHERE. Главная ментальная перестройка: не писать циклы по строкам (iterrows медленный и неидиоматичный), а оперировать колонками целиком.

Ниже — 72 результата eval-прогона классификатора тикетов: три версии промпта × четыре категории × 6 примеров. Сгруппируйте по-разному и посмотрите, как меняются выводы. Усы на графике pass rate — 95% доверительный интервал Уилсона.

Что стоит заметить на этих данных. По версиям v3 выглядит лучше всех, но в разрезе «версия × категория» видно, что v3 просела на billing (3 из 6 против 5 и 4 у v1 и v2) — при n = 6 на ячейку это может быть и шум, и реальная регрессия, интервалы огромные. v3 также медленнее и расходует больше выходных токенов. Решение «катим v3» требует больше данных по billing и оценки стоимости, а не одного числа в сводке. Именно это — работа AI engineer с evals. Здесь pandas — инструмент; методология целиком (golden dataset, LLM-as-a-judge, размер выборки, quality gate в CI) — в модуле 8.

import pandas as pd

df = pd.concat(pd.read_parquet(p) for p in ["results_v1.parquet", "results_v2.parquet", "results_v3.parquet"])
df = df[df.error.isna()]  # инфраструктурные ошибки — отдельно, не в качестве

# 1. Сводка по версиям: качество, латентность, стоимость
PRICE_IN, PRICE_OUT = 1 / 1e6, 5 / 1e6  # Haiku 4.5, $ за токен (на момент написания)
df["cost_usd"] = df.input_tokens * PRICE_IN + df.output_tokens * PRICE_OUT
summary = df.groupby("prompt_version").agg(
    pass_rate=("passed", "mean"),
    n=("passed", "size"),
    p50_ms=("latency_ms", "median"),
    p95_ms=("latency_ms", lambda s: s.quantile(0.95)),
    cost_per_1k=("cost_usd", lambda s: s.mean() * 1000),
)

# 2. Срезы: где именно выросло или упало
pivot = df.pivot_table(index="category", columns="prompt_version",
                       values="passed", aggfunc="mean").round(2)
pivot["delta_v3_v2"] = pivot["v3"] - pivot["v2"]

# 3. Парное сравнение на одних и тех же примерах: смотрим только расхождения
wide = df.pivot_table(index="example_id", columns="prompt_version", values="passed")
fixed = ((wide.v2 == 0) & (wide.v3 == 1)).sum()
broken = ((wide.v2 == 1) & (wide.v3 == 0)).sum()
print(f"v3 починил {fixed}, сломал {broken}")  # для McNemar важны только эти два числа

# 4. Провалы глазами: самое полезное действие в анализе evals
print(df.query("prompt_version == 'v3' and passed == 0")[["example_id", "category", "expected", "got"]])

SDK провайдеров

Официальные SDK Anthropic и OpenAI генерируются из OpenAPI-спецификаций и устроены похоже: типизированные запросы и ответы, sync и async клиенты, встроенные ретраи (у Anthropic по умолчанию 2 повтора на 408/409/429/5xx), таймауты, стриминг, пагинация. Всегда используйте их вместо ручного HTTP — кроме случаев, когда нужно понять протокол или SDK нет для вашего языка.

import anthropic

client = anthropic.Anthropic()  # ANTHROPIC_API_KEY из окружения

resp = client.messages.create(
    model="claude-opus-5",
    max_tokens=2048,                     # обязателен
    system="Отвечай по-русски, кратко.",  # system — параметр верхнего уровня, не роль
    messages=[{"role": "user", "content": "Чем HNSW лучше IVF?"}],
)
text = "".join(b.text for b in resp.content if b.type == "text")  # ответ — список блоков
print(resp.stop_reason, resp.usage.input_tokens, resp.usage.output_tokens)

# Стриминг с помощником, собирающим итоговое сообщение
with client.messages.stream(model="claude-opus-5", max_tokens=2048,
                            messages=[{"role": "user", "content": "Расскажи про BM25"}]) as s:
    for chunk in s.text_stream:
        print(chunk, end="", flush=True)
    final = s.get_final_message()

# Ошибки — иерархия исключений
try:
    client.messages.create(model="claude-opus-5", max_tokens=10, messages=[])
except anthropic.BadRequestError as e:      # 400 — не ретраить
    print("bad request:", e.message)
except anthropic.RateLimitError:            # 429 — SDK уже ретраил max_retries раз
    raise
except anthropic.APIStatusError as e:       # остальные HTTP-ошибки
    print(e.status_code)

from openai import OpenAI

client = OpenAI()  # OPENAI_API_KEY из окружения
MODEL = "..."      # актуальное имя модели — из документации OpenAI

# Responses API — основной интерфейс OpenAI; Chat Completions остаётся для совместимости
resp = client.responses.create(
    model=MODEL,
    instructions="Отвечай по-русски, кратко.",  # аналог system
    input="Чем HNSW лучше IVF?",
)
print(resp.output_text)                          # хелпер: склеенный текст ответа
print(resp.usage.input_tokens, resp.usage.output_tokens)

# Старый стиль, который встретится в чужом коде и во многих совместимых API (vLLM, Ollama):
chat = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "system", "content": "Кратко."},
              {"role": "user", "content": "Что такое BM25?"}],
)
print(chat.choices[0].message.content, chat.choices[0].finish_reason,
      chat.usage.prompt_tokens, chat.usage.completion_tokens)

LangChain, LlamaIndex, LangGraph

Фреймворки — самая спорная тема в прикладном AI. На собеседовании ждут не «я знаю LangChain», а взвешенного мнения: что он даёт, чем платите, когда брать.

Чем платите — список, который стоит уметь назвать:

• Скрытые промпты. Готовые цепочки и агенты содержат свои системные промпты и шаблоны. Вы не видите, что уходит в модель, пока не включите трейсинг. Anthropic в «Building effective agents» прямо советует начинать с прямых вызовов API: фреймворки добавляют слои, скрывающие реальные промпты и ответы, и провоцируют лишнюю сложность.
• Отладка. Стектрейс на 40 фреймов через generic-обёртки, callbacks и runnable-протоколы. Ошибка формата ответа модели выглядит как исключение глубоко внутри парсера.
• Версии. Экосистема быстро меняет API; мажорные переходы ломали импорты и паттерны, туториалы годичной давности часто не работают. Пинить версии и закладывать время на миграции.
• Отставание от провайдера. Новая возможность API (новый параметр, тип блока, режим кэширования) появляется в SDK провайдера в день релиза, во фреймворке — позже, а в «универсальной» абстракции может не появиться вовсе.
• Наименьший общий знаменатель. Абстракция «chat model» сглаживает различия провайдеров, в том числе полезные.
• Зависимости. Десятки транзитивных пакетов, конфликты версий с вашим pydantic или numpy.

// LangChain4j: декларативный сервис поверх модели. Удобно, но промпт собирает фреймворк.
interface Triage {
    @SystemMessage("Классифицируй тикет: billing, tech, refund или other. Ответь одним словом.")
    String classify(@UserMessage String ticket);
}

ChatModel model = AnthropicChatModel.builder()
        .apiKey(System.getenv("ANTHROPIC_API_KEY"))
        .modelName("claude-haiku-4-5")
        .logRequests(true)  // с первого дня: видеть, что реально уходит в модель
        .logResponses(true)
        .build();
Triage triage = AiServices.create(Triage.class, model);
String label = triage.classify("Не прошла оплата картой");

// Spring AI: ChatClient из автоконфигурации (spring-ai-starter-model-anthropic).
String label2 = chatClient.prompt()
        .system("Классифицируй тикет: billing, tech, refund или other. Ответь одним словом.")
        .user("Не прошла оплата картой")
        .call()
        .content();

Jupyter: для экспериментов, не для прода

Jupyter notebook — документ из ячеек кода и текста, которые выполняются в живом процессе (kernel) по одной. Для работы с LLM это идеальная лаборатория: поправил промпт, перезапустил одну ячейку, посмотрел пять ответов рядом, построил график по результатам evals, записал выводы тут же. Состояние (загруженный датасет, клиент) живёт между ячейками, не нужно перезапускать всё.

Ровно это же делает его непригодным для прода:

• Скрытое состояние. Ячейки выполняются в любом порядке, переменная могла быть определена в удалённой ячейке. Ноутбук «работает у меня» и не воспроизводится после Restart & Run All.
• Нет тестов, типов, ревью. Файл .ipynb — JSON с выводами и картинками в base64; диффы в git нечитаемы. Помогают nbstripout (очистка выводов), jupytext (парный .py), или marimo — реактивные ноутбуки, хранящиеся как обычный .py.
• Утечки. Выводы ячеек сохраняются в файле: ответы модели с ПДн, случайно напечатанный ключ API уезжают в репозиторий.
• Нет жизненного цикла сервиса: ни graceful shutdown, ни лимитов, ни наблюдаемости.

Нормальный путь: ноутбук → код, который доказал ценность, выносится в модуль с функциями → скрипт с аргументами (PEP 723) → тесты и CI → при необходимости сервис (FastAPI или GoSpring Boot). Ноутбук остаётся как отчёт об эксперименте, импортирующий этот модуль.

Coding agents в работе AI-инженера

Coding agent — LLM в агентном цикле с инструментами разработчика: читать и искать по коду, править файлы, запускать команды (go testmvn verify, git diff), вызывать MCP-серверы. Это тот же цикл tool use из модуля 2, только «мир» агента — ваш репозиторий (как цикл устроен изнутри, разберём в модуле 6). Код — область, где агенты работают лучше всего: компилятор и тесты дают объективную обратную связь без человека. Отсюда главный принцип: доверие к изменению от агента строится на проверяемости, а не на уверенном тоне отчёта. То, что автоматически не проверяется (промпты, тексты, конкурентность, безопасность), требует evals и человека.

Классы инструментов

Сравнивайте не бренды, а свойства: какой файл инструкций читается, какие есть режимы разрешений и sandbox, поддерживается ли MCP, где исполняется код и какие секреты туда попадают.

Рабочий цикл

1. Исследование без права правок (в Claude Code — plan mode, --permission-mode plan). Большое исследование — субагенту, чтобы не засорять основной контекст.
2. План письменно: файлы, функции, тесты, чего не трогать. Правка плана стоит одного сообщения, правка 600 строк диффа — часа.
3. Тесты сначала: агент пишет табличный тестпараметризованный тест (@ParameterizedTest), запускает, тест падает по правильной причине. Тесты коммитятся отдельно, до реализации.
4. Реализация маленькими шагами: «сделай так, чтобы тесты прошли; тесты не меняй». Коммит после зелёных go vet и go test -raceзелёного mvn verify (компиляция, линтеры, тесты).
5. Ревью диффа: сначала git diff --stat (не вышел ли за план), потом отдельно дифф *_test.go*Test.java (не ослаблены ли проверки), потом всё. Агент пишет, человек отвечает за мерж.

Настройка репозитория: AGENTS.md, права, хуки

Файл инструкций агент загружает в контекст в начале каждой сессии. AGENTS.md — открытый формат (обычный Markdown), его читают Codex, Cursor, Copilot и большинство других агентов; вложенные файлы в подкаталогах уточняют правила, приоритет у ближайшего. Claude Code читает CLAUDE.md (а AGENTS.md — если CLAUDE.md нет); для команды со смешанными инструментами удобно держать правила в AGENTS.md, а в CLAUDE.md написать строку @AGENTS.md и специфику Claude Code. Пишите только то, чего агент не выведет из кода: команды проверки, карту, неочевидные конвенции, запреты, критерий «готово». Каждая строка едет в контекст каждой сессии — это «всегда загруженная» часть контекста (модуль 6), документация Claude Code советует держаться в пределах ~200 строк.

Но инструкция — не гарантия: документация Claude Code прямо называет CLAUDE.md контекстом, а не принудительной конфигурацией. То, что должно выполняться всегда, живёт в двух механизмах вне модели. Права: режим решает, спрашивать ли человека (в Claude Code — от Manual с подтверждениями до auto, где действия проверяет модель-классификатор, и bypassPermissions — только в изолированном контейнере), правила allow/ask/deny уточняют его, а sandbox средствами ОС ограничивает, до каких файлов и доменов вообще дотянутся shell-команды. Правила для команд хрупкие (вариация синтаксиса их обходит), поэтому граница безопасности — sandbox или контейнер. Хуки: ваши команды на событиях агента; PreToolUse с кодом выхода 2 блокирует вызов инструмента, Stop с кодом 2 не даёт агенту закончить ход и возвращает ему stderr.

# docrag — RAG по документации (Java 21, Spring Boot, Postgres + pgvector)

## Команды
- `docker compose up -d db` — Postgres для интеграционных тестов (или Testcontainers)
- `make check` — ./mvnw -q verify: spotless:check, компиляция с Error Prone, тесты; запускай перед «готово»
- `make eval-smoke` — ~40 вопросов из golden set; обязателен при правке prompts/ и src/main/java/docrag/generate/

## Структура и конвенции
- docrag.retrieve — гибридный поиск; docrag.generate — промпт и вызов Claude; prompts/ — версии промптов
- Ошибки: доменные исключения с причиной (new XxxException("...", e)); логи только SLF4J; имена моделей — из generate/Models.java

## Нельзя
- Менять evals/data/ (эталон) и применённые migrations/*.sql (Flyway); ослаблять тесты, ставить @Disabled
- Добавлять зависимости в pom.xml без вопроса, читать .env, ходить в прод

## Готово, когда
- make check зелёный; при правке prompts/ — eval-smoke не хуже baseline; дифф ≤ 300 строк

{
  "permissions": {
    "allow": ["Bash(make check)", "Bash(./mvnw test *)", "Bash(git diff *)"],
    "ask":   ["Bash(git push *)", "Edit(/pom.xml)", "Edit(/migrations/**)"],
    "deny":  ["Read(./.env)", "Edit(/evals/data/**)", "Bash(kubectl *)"]
  },
  "sandbox": {
    "enabled": true,
    "filesystem": { "denyRead": ["./.env", "~/.ssh", "~/.aws", "~/.kube"] },
    "network": { "allowedDomains": ["repo.maven.apache.org"] }
  },
  "hooks": {
    "Stop": [{ "hooks": [{ "type": "command", "timeout": 900,
      "command": "cd \"$CLAUDE_PROJECT_DIR\" && java -jar tools/agentgate.jar" }] }]
  }
}

# docrag — RAG по документации (Go, Postgres + pgvector)

## Команды
- `docker compose up -d db` — Postgres для интеграционных тестов
- `make check` — gofmt -l, go vet, go test -race ./...; запускай перед «готово»
- `make eval-smoke` — ~40 вопросов из golden set; обязателен при правке prompts/ и internal/generate/

## Структура и конвенции
- internal/retrieve — гибридный поиск; internal/generate — промпт и вызов Claude; prompts/ — версии промптов
- Ошибки: fmt.Errorf("...: %w", err); логи только slog; имена моделей — из internal/generate/models.go

## Нельзя
- Менять evals/data/ (эталон) и применённые migrations/*.sql; ослаблять или пропускать тесты
- Добавлять зависимости без вопроса, читать .env, ходить в прод

## Готово, когда
- make check зелёный; при правке prompts/ — eval-smoke не хуже baseline; дифф ≤ 300 строк

{
  "permissions": {
    "allow": ["Bash(make check)", "Bash(go test *)", "Bash(git diff *)"],
    "ask":   ["Bash(git push *)", "Bash(go get *)", "Edit(/migrations/**)"],
    "deny":  ["Read(./.env)", "Edit(/evals/data/**)", "Bash(kubectl *)"]
  },
  "sandbox": {
    "enabled": true,
    "filesystem": { "denyRead": ["./.env", "~/.ssh", "~/.aws", "~/.kube"] },
    "network": { "allowedDomains": ["proxy.golang.org", "sum.golang.org"] }
  },
  "hooks": {
    "Stop": [{ "hooks": [{ "type": "command", "timeout": 900,
      "command": "cd \"$CLAUDE_PROJECT_DIR\" && go run ./cmd/agentgate" }] }]
  }
}

Stop-хук agentgate превращает «готово, когда» из AGENTS.md в код: смотрит, что изменилось относительно main, и решает, какие проверки обязательны.

// plan по изменениям возвращает обязательные проверки (цели Makefile — те же,
// что перечислены в AGENTS.md) и нарушения, которые агент должен откатить.
public static Plan plan(List<Change> cs) {
    boolean javaCode = false, prompts = false;
    List<String> violations = new ArrayList<>();
    for (Change c : cs) {
        String p = c.path();
        if (p.startsWith("evals/data/")) {
            violations.add(p + ": эталон evals меняет человек отдельным PR, а не агент вместе с кодом");
        } else if (p.startsWith("migrations/") && c.status() != 'A') {
            violations.add(p + ": применённую миграцию не правят, добавьте новую");
        } else if (p.startsWith("prompts/")) {
            prompts = true;
        } else if (p.endsWith(".java") || p.equals("pom.xml") || p.endsWith("/pom.xml")) {
            javaCode = true;
        }
    }
    List<List<String>> checks = new ArrayList<>();
    if (javaCode) {
        checks.add(List.of("make", "check")); // mvn verify: компиляция, линтеры, тесты
    }
    if (prompts) {
        checks.add(List.of("make", "eval-smoke")); // промпт не проверить юнит-тестом
    }
    return new Plan(checks, violations);
}

// Plan по изменениям возвращает обязательные проверки (цели Makefile — те же,
// что перечислены в AGENTS.md) и нарушения, которые агент должен откатить.
func Plan(cs []Change) (checks [][]string, violations []string) {
	var goCode, prompts bool
	for _, c := range cs {
		switch {
		case strings.HasPrefix(c.Path, "evals/data/"):
			violations = append(violations, c.Path+": эталон evals меняет человек отдельным PR, а не агент вместе с кодом")
		case strings.HasPrefix(c.Path, "migrations/") && c.Status != 'A':
			violations = append(violations, c.Path+": применённую миграцию не правят, добавьте новую")
		case strings.HasPrefix(c.Path, "prompts/"):
			prompts = true
		case strings.HasSuffix(c.Path, ".go"), c.Path == "go.mod", c.Path == "go.sum":
			goCode = true
		}
	}
	if goCode {
		checks = append(checks, []string{"make", "check"}) // gofmt -l, go vet, go test -race
	}
	if prompts {
		checks = append(checks, []string{"make", "eval-smoke"}) // промпт не проверить go test
	}
	return checks, violations
}

Полная версия (запуск git и проверок, коды выхода 0/1/2, табличные тестыпараметризованные JUnit-тесты на fake-раннере) — в examples/m04-toolsexamples/java/m04-tools репозитория курса. Нарушения и упавшие проверки хук пишет в stderr с хвостом лога, и агент продолжает работу. От зацикливания Claude Code защищён сам: после 8 продолжений от Stop-хуков подряд он завершает ход (счётчик сбрасывается при каждом вызове инструмента; порог меняет CLAUDE_CODE_STOP_HOOK_BLOCK_CAP, по состоянию на октябрь 2026). make eval-smoke ходит в API модели с ключом, поэтому его запускает хук (хуки работают вне sandbox), а не агент из своего shell.

Безопасность

• Секреты и прод. Всё, что агент прочитал, попадает в контекст, а оттуда — в логи и, при инъекции, к атакующему. Агенту — dev-ключи с лимитом расходов и токены со scope на один репозиторий; никаких DSN прод-БД, kube-контекста прода и облачных admin-ключей: DROP TABLE не откатывается. Данные — через read-only MCP-инструмент с allowlist запросов (как db_query в проекте C).
• Prompt injection. Агент читает чужой текст: README и код зависимостей, issues и комментарии в PR, веб-страницы, ответы MCP-инструментов. Это lethal trifecta из модуля 3: приватный код + недоверенный текст + каналы наружу (сеть, git push, публичный комментарий). Пример: Invariant Labs (2025) через вредоносный issue заставили агента с GitHub MCP-сервером выложить данные приватных репозиториев в публичный PR. Защита — минимальные права, allowlist сети, подтверждение действий, выносящих данные наружу; систематически — в модуле 7.
• MCP-серверы проекта описываются в .mcp.json (в git, секреты — через ${VAR}). Для docrag естественный кандидат — ваш docs-mcp из проекта C (модуль 6). Каждый сервер — новые права и новый источник недоверенного текста: по умолчанию только чтение, свои или прочитанные вами серверы, версии зафиксированы.

Типичные провалы и как их ловить

Ощущение скорости — не метрика: в исследовании METR (2025) опытные разработчики с AI-инструментами работали на 19% дольше, хотя считали, что ускорились. Меряйте своё: время до мержа и долю PR от агента, которые пришлось переделать.

Специфика AI-инженерии

• Агент правит промпт — обязателен прогон evals. Зелёный go testmvn verify ничего не говорит о поведении модели. То же для кода вокруг модели: сборки контекста, параметров вызова, парсинга ответа, retrieval. Smoke-набор — до мержа, полный — в CI (модуль 8).
• Агент правит эталон evals — конфликт интересов. Если в одном диффе меняются и код, и ожидаемые ответы, зелёный результат ничего не доказывает. Эталон меняет человек отдельным PR; обеспечивают это deny-правило, CODEOWNERS и хук.
• Агент генерирует eval-кейсы — полезно для покрытия (перефразировки, граничные случаи, атаки, вопросы без ответа), но: ожидаемый ответ задаёт человек или источник, а не модель (иначе её ошибки становятся эталоном); проверяйте разнообразие и то, что текущая версия падает хотя бы на части кейсов; не тащите в фикстуры реальные логи с ПДн; помечайте "source": "synthetic". Подробно — в модулях 8 и 10.

Обратите внимание: правка промпта без evals и эталон evals в одном диффе с кодом — блокеры при любом числе ревьюеров, а ревью 1 200 строк снижает риск втрое слабее, чем ревью 150. Командные правила работы с агентами (что можно отдавать, как ревьюить) — в модуле 13.

Практика

Самопроверка

Вопросы с собеседований

Источники

• uv — документация; PEP 723 — inline script metadata
• Python — asyncio (TaskGroup, timeout, to_thread)
• Pydantic v2
• FastAPI (async, StreamingResponse)
• pandas — документация; DuckDB; Polars
• anthropic-sdk-python; документация Anthropic
• openai-python; документация OpenAI
• Anthropic — Building effective agents (раздел о фреймворках)
• LangChain, LangGraph, LlamaIndex
• LangChain4j, Spring AI, anthropic-sdk-java
• langchaingo, Eino
• Jupyter, marimo, nbstripout
• Hamel Husain — Your AI Product Needs Evals (анализ ошибок глазами)
• Claude Code — Best practices (исследование → план → код, проверяемость, управление контекстом) и Anthropic — Claude Code: best practices for agentic coding
• Claude Code: CLAUDE.md и AGENTS.md, режимы разрешений, правила allow/ask/deny, sandbox, хуки, MCP
• AGENTS.md (формат и список инструментов) и Linux Foundation — Agentic AI Foundation (декабрь 2025)
• OpenAI Codex: репозиторий Codex CLI, AGENTS.md в Codex, sandbox и подтверждения
• Cursor — Rules и Cloud Agents; GitHub — Copilot cloud agent; JetBrains AI Assistant — агенты и Agent Client Protocol
• Google — Transitioning Gemini CLI to Antigravity CLI (май 2026)
• Invariant Labs — GitHub MCP Exploited (инъекция через issue, утечка из приватного репозитория)
• Spracklen et al., 2025 — We Have a Package for You! (package hallucinations)
• METR — исследование продуктивности опытных open-source разработчиков (2025) и обновление 2026 года