BMITECH · 01.LAB

API-ключи: установка, настройка, паттерны и бюджет токенов

Практика BMITECH × МФТИ · три команды · один ключ на команду · любой клиент: OpenCode, IDE, ChatGPT, Claude Desktop

КодENV-01ПроектBMITECH × MIPTДата16 ноября 2026Статускратко / детально · 3 профиля команд · 6 паттернов · бюджет 80/20Версия1.0
Скиллы 01.labSKL_project_logSKL_doc

Ключ API — это не «доступ к чату», а расходуемый ресурс с ценой за токен. На практику выдаётся три ключа — по одному на команду. Задача этой инструкции: поставить инструменты, подключить ключ так, чтобы он не утёк, и научиться тратить токены осознанно — чтобы к третьей неделе не остаться без бюджета на отчёт.

Ключей
3
по одному на команду, не на человека
Правило бюджета
80 / 20
80% вызовов — дешёвая модель, 20% — сильная
Секретов в git
0
ключ только в .env, вне репозитория
Старт
16.11
ключ проверен smoke-тестом до первой задачи

Порядок действий. (1) получить ключ у BMITECH → (2) поставить Python и клиент → (3) положить ключ в .env → (4) прогнать smoke-тест → (5) зафиксировать лимиты и журнал расходов → (6) работать по паттернам из раздела 6.

Две части инструкции. Слева в навигации — «Кратко»: только установка, шесть шагов. «Детально»: ключи и доступы, настройка клиентов, проверка, шесть паттернов, бюджет токенов, профили команд, антипаттерны, диагностика и правила по данным.

Что читать, если время ограничено. Разделы 2 (ключи), 4 (настройка), 5 (проверка) — обязательны для всех. Раздел 8 — ваш командный профиль: какие модели и промпты нужны именно вам. Раздел 7 — бюджет: прочитать до первого большого прогона, не после.

Клиент — любой, ключ один. Аккаунт «API Code» отдаёт стандартный OpenAI-совместимый протокол, поэтому работать можно там, где вам удобно:

  • OpenCode (терминал) — агент читает репозиторий и правит файлы;
  • любая IDE — VS Code, PyCharm, Cursor, Zed с плагином (Continue, Cline, Roo, Copilot-совместимые) — достаточно указать свой base_url и ключ;
  • ChatGPT (веб/десктоп) и Claude Desktop — если клиент позволяет подключить своего провайдера (custom endpoint, MCP-коннектор); если нет, они остаются отдельными инструментами, а ключ работает в IDE и терминале;
  • Python SDK и curl — когда нужен воспроизводимый прогон или батч.

Инструкция показывает два референсных пути — OpenCode и Python SDK. Остальные клиенты настраиваются теми же двумя параметрами: адрес API и ключ.

Одна оговорка про сервис. В инструкции используются два плейсхолдера: <BASE_URL> (адрес API из личного кабинета, обычно вида https://<host>/v1) и <MODEL> (имя модели из списка в кабинете). Точные значения берутся в кабинете «API Code»: раздел API → Endpoint / Base URL, Models, Limits. Если сервис отдаёт не OpenAI-совместимый протокол — скажите наставнику, добавим отдельный коннектор.

Если нужно просто получить работающий ключ — этот раздел. Шесть шагов, без объяснений. Разбор ошибок, паттерны, бюджет и профили команд — во вкладке «Детально».

0. Что нужно. Ключ команды (выдаёт BMITECH), Python 3.11+, 10–15 минут и терминал.

1. Ключ — в файл .env, в корне репозитория.

APICODE_BASE_URL=https://<BASE_URL>/v1
APICODE_API_KEY=<ключ-команды>
APICODE_MODEL_CHEAP=<дешёвая-модель>

2. Окружение и SDK.

python -m venv .venv
.venv\Scripts\activate          # Windows
source .venv/bin/activate        # macOS / Linux
pip install openai python-dotenv

3. Клиент — на выбор. OpenCode (npm install -g opencode-ai), любая IDE с плагином (Continue, Cline, Cursor — указать base_url и ключ), ChatGPT или Claude Desktop, если там подключается свой провайдер, либо Python/curl. Дальше в примерах — Python и OpenCode.

4. Проверить ключ одним запросом.

# check_key.py
import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
c = OpenAI(base_url=os.environ["APICODE_BASE_URL"], api_key=os.environ["APICODE_API_KEY"])
r = c.chat.completions.create(
    model=os.environ["APICODE_MODEL_CHEAP"],
    messages=[{"role": "user", "content": "Ответь одним словом: работает"}],
    max_tokens=16,
)
print(r.choices[0].message.content, r.usage)

5. Первый рабочий запрос. Не «привет», а задача с критерием приёмки: что на входе, что на выходе, в каком формате.

python check_key.py   # ждём: работает + usage с токенами

6. Закрыть риски в тот же день. .env в .gitignore; usage.jsonl в .gitignore и в работу; лимит ключа записан в docs/ai_log/keys.md (без самого ключа).

Если ответа нет: 401 — ключ или .env; 404 — имя модели; 429 — лимит; CERTIFICATE_VERIFY_FAILED — прокси. Полная таблица — вкладка «Детально» → «Диагностика».

Модель доступа. Один аккаунт «API Code» на практику, внутри — три ключа с жёстким лимитом на каждый. Ключ принадлежит команде, а не человеку: если один студент уйдёт — ключ остаётся команде. Хранитель ключа — тимлид-инженер, тот, кто ведёт репозиторий и умеет работать с git.

КомандаЗадачиПеременнаяХранительГде лежит
T1 · EvidenceHL-01…HL-02, MIPT-13: ассистент с цитатами, оценка качестваAPICODE_API_KEYУчастник 3 · pandas, git.env в корне репозитория команды
T2 · NavigatorMIPT-32, HL-03, HL-05: RAG по базе знаний, коннекторыAPICODE_API_KEYУчастник 1 · Python, git.env в корне репозитория команды
T3 · AnalystHAB-01…04, MIPT-11/12: привычки на открытых данных, аналитикаAPICODE_API_KEYУчастник 2 · Python, git.env в корне репозитория команды

Имя переменной одинаковое во всех командах — так проще переносить код между репозиториями. Различаются сами ключи, а не имена.

Как получить ключ.

  • ☐ BMITECH создаёт три ключа в кабинете и ставит лимит на каждый (hard limit)
  • ☐ Ключ передаётся команде по защищённому каналу, не в общий чат
  • ☐ Тимлид кладёт ключ в .env, добавляет .env в .gitignore
  • ☐ Smoke-тест из раздела 5 проходит: ответ получен, usage не пустой
  • ☐ В docs/ai_log/keys.md записаны: команда, дата выдачи, лимит, последние 4 символа ключа

Правила, которые не обсуждаются.

  • Ключ не коммитится, не вставляется в скриншоты, не пересылается в чат — ни в общий, ни в личный.
  • В отчётах и демо ключ маскируется: ac-t1-••••7f2a.
  • Утечка = немедленный отзыв ключа и выпуск нового; цена — один вечер простоя, а не весь бюджет практики.
  • Ключ не используется для личных проектов вне практики: лимит общий, и его не восстановят.
  • В конце практики ключи отзываются — это часть сдачи, а не бюрократия.

Типичная ошибка первой недели. Ключ вставляют прямо в код ноутбука, ноутбук коммитят в репозиторий, через день ключ утекает в историю git. Вычистить историю сложнее, чем отозвать ключ. Поэтому .env и .gitignore создаются до первого запроса.

Три инструмента — три роли. Терминальный агент (OpenCode) — для работы с кодом и файлами проекта. Python + SDK — для скриптов, батчей и воспроизводимых прогонов. curl — чтобы за 10 секунд понять, живой ли ключ, не поднимая окружение.

ИнструментЧто даётКогда нужен
OpenCode (CLI/TUI)Агент: читает репозиторий, правит файлы, запускает командыРазработка, рефакторинг, разбор ошибок, документация
Python 3.11+ и openaiСкрипты: батчи, judge, RAG, замер метрикПакетная обработка, эксперименты, воспроизводимость
curlОдин HTTP-запрос без зависимостейПроверка ключа, диагностика 401/429

Достаточно поставить всё три: занимает 10–15 минут, экономит часы на второй неделе.

1. Проверить, что уже есть.

python --version      # нужен 3.11 или новее
git --version
node --version        # нужен 20+ для OpenCode
curl --version

2. Python-окружение (обязательно для всех). Отдельное окружение на проект — чтобы версии библиотек не конфликтовали между командами и задачами.

cd <папка-репозитория-команды>
python -m venv .venv

# Windows (PowerShell)
.venv\Scripts\Activate.ps1
# Windows (cmd)
.venv\Scripts\activate.bat
# macOS / Linux
source .venv/bin/activate

python -m pip install --upgrade pip
pip install openai python-dotenv tiktoken

3. Терминальный агент. Если OpenCode ещё не установлен:

npm install -g opencode-ai
# альтернатива для macOS/Linux:
curl -fsSL https://opencode.ai/install | bash

opencode --version

Если pip install падает с CERTIFICATE_VERIFY_FAILED — это корпоративный прокси или антивирус подменяет сертификат, а не «сломанный Python». Быстрое решение — доверить конкретные хосты на один запуск, не отключая проверку глобально: pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org openai. Правильное — поставить корневой сертификат организации. Если не получается за 10 минут — пишите наставнику, а не воюйте с сетью в одиночку.

Принцип. Ключ и адрес API живут в одном месте — в .env. Код читает их из переменных окружения. Никаких api_key="sk-..." в ноутбуках, скриптах и конфигах, которые попадают в git.

Шаг 1. Файл .env в корне репозитория команды.

APICODE_BASE_URL=https://<BASE_URL>/v1
APICODE_API_KEY=<ключ-команды>
APICODE_MODEL_CHEAP=<дешёвая-модель>
APICODE_MODEL_STRONG=<сильная-модель>

Шаг 2. .gitignore — до первого коммита.

.env
.env.*
.venv/
usage.jsonl
docs/ai_log/raw/
__pycache__/
.ipynb_checkpoints/

Шаг 3. Загрузчик конфигурации — один файл, который импортируют все скрипты команды. Так ключ читается ровно в одном месте, и его легко заменить.

# config.py — единая точка подключения к API
import os
from pathlib import Path
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv(Path(__file__).with_name(".env"))

BASE_URL = os.environ["APICODE_BASE_URL"]
MODEL_CHEAP = os.environ.get("APICODE_MODEL_CHEAP", "")
MODEL_STRONG = os.environ.get("APICODE_MODEL_STRONG", "")

client = OpenAI(base_url=BASE_URL, api_key=os.environ["APICODE_API_KEY"])

Шаг 4. Конфиг терминального агента. Проектный opencode.json в корне репозитория: провайдер объявляется как OpenAI-совместимый, ключ подставляется из переменной окружения.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "apicode": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "API Code",
      "options": {
        "baseURL": "https://<BASE_URL>/v1",
        "apiKey": "{env:APICODE_API_KEY}"
      },
      "models": {
        "<дешёвая-модель>": { "name": "cheap" },
        "<сильная-модель>": { "name": "strong" }
      }
    }
  },
  "model": "apicode/<дешёвая-модель>"
}

Альтернатива без файла — сохранить ключ в хранилище агента: opencode auth login, выбрать провайдера, вставить ключ. Он ляжет в ~/.local/share/opencode/auth.json и не попадёт в репозиторий. Для практики удобнее .env: конфиг виден в проекте, а ключ — нет.

Шаг 5. Переменные окружения — если .env не используется (например, ключ нужен только в текущей сессии терминала).

# Windows cmd (постоянно, для новых окон)
setx APICODE_API_KEY "<ключ-команды>"

# PowerShell (только текущая сессия)
$env:APICODE_API_KEY = "<ключ-команды>"

# macOS / Linux (только текущая сессия)
export APICODE_API_KEY="<ключ-команды>"
Что нужноГде взятьКак проверить
Base URLКабинет: раздел API → Endpointcurl $APICODE_BASE_URL/models отвечает 200
Имя моделиКабинет: раздел Models (копировать как есть)Модель появляется в ответе /models
Лимит ключаКабинет: раздел Limits / UsageВ ответе есть блок usage, в кабинете виден расход

Не угадывайте имена моделей: опечатка в имени даёт 404 «model not found», который легко принять за проблему с ключом.

Правило. Пока smoke-тест не прошёл, ничего не пишем и никого не просим «починить ключ». Тест занимает минуту и отвечает на 90% вопросов: жив ли ключ, тот ли адрес, существует ли модель, отдаёт ли сервис статистику токенов.

Тест 1 — список моделей. Не тратит токены и сразу показывает доступные имена.

curl -s "$APICODE_BASE_URL/models" \
  -H "Authorization: Bearer $APICODE_API_KEY" | head -c 600

Тест 2 — минимальный запрос из Python. Печатает ответ и расход токенов.

# check_key.py
from config import client, MODEL_CHEAP

r = client.chat.completions.create(
    model=MODEL_CHEAP,
    messages=[{"role": "user", "content": "Ответь одним словом: работает"}],
    max_tokens=16,
)
print("ответ:", r.choices[0].message.content)
print("токены:", r.usage)

Что означает результат.

СимптомЧто этоЧто делать
работает и usage не пустойВсё в порядкеЗаписать дату проверки в docs/ai_log/keys.md
401 UnauthorizedКлюч неверный, отозван или скопирован с пробеломПеревыпустить/перекопировать ключ, проверить .env
403 ForbiddenКлюч верный, но нет доступа к модели или регионуПроверить список моделей в кабинете
404 model not foundОпечатка в имени моделиСкопировать имя из /models или кабинета
429 Too Many RequestsПревышен rate limit или бюджетПауза 30–60 с, затем батч меньшего размера

Скриншот успешного теста приложите к отчёту недели 1 — это доказательство, что команда стартовала, а не «начала разбираться».

  • ☐ /models отвечает 200, имя модели скопировано без опечаток
  • ☐ check_key.py печатает ответ и usage с ненулевыми токенами
  • ☐ git status не показывает .env; git grep -n "<первые 6 символов ключа>" пуст
  • ☐ В docs/ai_log/keys.md есть запись: команда, дата, лимит, маска ключа

Зачем паттерны. Один и тот же вопрос можно задать так, что он будет стоить 200 токенов, и так, что 60 000 — с тем же результатом. Паттерн — это форма запроса, у которой предсказуемая цена и проверяемый результат.

ПаттернКогдаЦенаГлавный риск
P1 · Агент в терминалеКод, рефакторинг, разбор ошибок, документацияСредняя (растёт с контекстом)Агент тянет в контекст весь репозиторий
P2 · Батч-скриптРазметка, извлечение полей, массовая обработкаНизкая на элементДубли без кэша, гигантский один запрос
P3 · RAG с цитатамиОтветы по базе знаний, справка, проверка фактаСредняяОтвет без источника выглядит как факт
P4 · LLM-as-judgeОценка качества ответов по рубрикеСредняяСудья соглашается со всем подряд
P5 · Структурированный выводJSON для кода, таблиц, отчётовНизкаяНевалидный JSON ломает пайплайн
P6 · Документ → брифСтатьи, диплом, длинные PDFСредняяПотеря чисел и отрицаний при сжатии

Начинайте с P5 и P2: они дают предсказуемую цену. P1 включайте, когда задача действительно про код, а не «пусть агент посмотрит».

P1 · Агент в терминале. Одна задача — одна сессия. Перед стартом закрывайте лишние файлы и не давайте агенту весь репозиторий: он читает то, что упомянуто в задаче. Когда сессия разрослась — сжимайте контекст (/compact), а не продолжайте в том же окне.

opencode
# в сессии:
#   /init      — короткое описание репозитория
#   /compact   — сжать историю, сохранив суть
#   /model     — переключить модель (дешёвая ↔ сильная)

P2 · Батч-скрипт с кэшем. Один запрос на 20–50 коротких элементов, строгий формат ответа, результат в JSONL, повторные вопросы берутся из кэша. На 200 карточках это разница между 200 запросами и 5.

# batch.py — батч + кэш по хэшу входа
import hashlib, json
from pathlib import Path
from config import client, MODEL_CHEAP

CACHE = Path("cache.jsonl")

def load_cache() -> dict:
    if not CACHE.exists():
        return {}
    return {json.loads(l)["h"]: json.loads(l)["out"]
            for l in CACHE.read_text(encoding="utf-8").splitlines() if l.strip()}

def ask_batch(items: list[str]) -> list[str]:
    cache = load_cache()
    todo = [x for x in items if hashlib.sha1(x.encode()).hexdigest() not in cache]
    for i in range(0, len(todo), 25):
        chunk = todo[i:i + 25]
        prompt = ("Для каждого фрагмента верни JSON-массив объектов "
                  '{"i": номер, "поля": {...}}. Фрагменты:\n'
                  + "\n".join(f"{n}. {t}" for n, t in enumerate(chunk)))
        r = client.chat.completions.create(
            model=MODEL_CHEAP,
            messages=[{"role": "user", "content": prompt}],
            response_format={"type": "json_object"},
            max_tokens=1500,
        )
        out = json.loads(r.choices[0].message.content)
        with CACHE.open("a", encoding="utf-8") as f:
            for n, item in enumerate(chunk):
                f.write(json.dumps({"h": hashlib.sha1(item.encode()).hexdigest(),
                                    "out": out[n]}, ensure_ascii=False) + "\n")
    cache = load_cache()
    return [cache[hashlib.sha1(x.encode()).hexdigest()] for x in items]

P3 · RAG с цитатами. Retrieval делается локально (BM25, эмбеддинги, SQLite), модель получает только найденные фрагменты и отвечает с указанием источника. Без фрагментов — «нет данных», а не догадка.

Ты — ассистент по базе знаний. Отвечай ТОЛЬКО по фрагментам ниже.
Если ответа во фрагментах нет — напиши «нет данных» и укажи, чего не хватает.
Формат: 3–5 предложений, затем строка «Источники: [id, id]».

Фрагменты:
[1] ...
[2] ...

Вопрос: ...

P4 · LLM-as-judge. Рубрика на 4–5 критериев с числами, temperature=0, парный прогон двух версий ответа, калибровка на 20 примерах, размеченных человеком. Судья без калибровки — это генератор уверенных оценок, а не метрика.

Оцени ответ по трём критериям, каждый 1–5:
1) точность: нет утверждений, которых нет в источнике;
2) полнота: отвечает на вопрос целиком;
3) формат: соответствует требуемой структуре.
Верни JSON: {"точность": n, "полнота": n, "формат": n, "комментарий": "..."}

Вопрос: ...
Источник: ...
Ответ: ...

P5 · Структурированный вывод. Просите JSON-схему и валидируйте её кодом. Один retry на невалидный ответ, дальше — ошибка, а не «попробуем ещё десять раз».

P6 · Документ → бриф. Длинный текст сначала режется на разделы (локально), потом каждый раздел сжимается отдельно, потом тезисы собираются и проверяются человеком. Числа и отрицания — первое, что теряется при сжатии.

Сожми раздел до 5 тезисов. Сохрани все числа, единицы измерения и отрицания.
Формат: «- тезис (стр. N)». Не добавляй того, чего нет в тексте.

Как считаются токены. Отдельно вход (промпт + контекст) и выход (ответ), по разной цене. Дорогое — не количество вопросов, а размер контекста: каждый токен истории диалога оплачивается заново на каждом шаге. Русский текст дороже английского на 20–40% при том же смысле.

ЧтоТокеновВывод
Страница А4 текста500–800Документ на 30 страниц — это уже 20 тыс.
100 строк кода1200–1600Файл на 600 строк не влезает в дешёвый бюджет
Один ответ 3–5 предложений80–150Дёшево, если не тащить историю
Сессия агента на задачу20–60 тыс.Главный источник расхода
Батч из 25 карточек8–12 тыс. вход / 3–4 тыс. выходПредсказуемо и кэшируется

Оценки приблизительные (±30%). Точные цифры даёт usage в каждом ответе — по нему и считайте, а не по интуиции.

Формула стоимости. цена = вход/1e6 × цена_входа + выход/1e6 × цена_выхода. Ориентиры для расчёта (уточнить в кабинете): дешёвая модель ≈ $0.10–0.20 за 1M входа и $0.40–0.60 за 1M выхода; средняя ≈ $0.50 / $1.50; сильная ≈ $3 / $15. Разница между дешёвой и сильной — в 20–30 раз, поэтому правило «80% вызовов — дешёвая» экономит больше, чем любая оптимизация промпта.

Распределение лимита. Если ключ команды даёт Q токенов на три недели, то неделя 1 — 15%, неделя 2 — 50%, неделя 3 — 35%. Ниже пример для Q = 3 000 000.

ПериодДоляПример (Q = 3M)На что
Неделя 115%450 тыс.Установка, smoke-тесты, разведка данных
Неделя 250%1.5 млнОсновная работа: код, батчи, RAG, эксперименты
Неделя 335%1.05 млнДоводка, метрики, отчёт, подготовка защиты

Резерв 10% внутри каждой недели — на отладку. Команда, потратившая 100% к среде, в четверг работает без модели.

Распределение по типам работ (ориентир, корректируется по задаче).

РаботаДоляМодельПочему так
Код и правки40%дешёваяМного итераций, короткие ответы
Батч-обработка данных25%дешёваяКэшируется, повторяемо
Оценка качества (judge)15%средняяНужна устойчивость оценок
Архитектура, сложная отладка15%сильнаяЦена ошибки выше цены токенов
Тексты и отчёт5%дешёваяЧерновик правится человеком

Правило переключения: если задача формулируется как «объясни/поправь/перепиши» — дешёвая. Если «спроектируй/почему не работает/что здесь не так» — сильная.

Десять правил экономии.

  1. Одна задача — одна сессия. Новая тема — новый контекст.
  2. Не пересказывайте историю: сжимайте её (/compact) или начинайте заново.
  3. max_tokens на выход: 512–1500 для рутины, больше — только осознанно.
  4. Батч 20–50 элементов вместо 50 отдельных запросов.
  5. Кэш по хэшу входа: повторный вопрос не должен стоить денег.
  6. Сначала 20 примеров и замер качества — потом прогон на всём корпусе.
  7. Retrieval вместо «вот весь документ, найди сам».
  8. Черновики — дешёвой моделью, финальная версия — сильной, и только она.
  9. Журнал usage.jsonl и разбор раз в неделю: где реально ушёл бюджет.
  10. Алерты на 50/80/100% — заранее, а не когда ключ перестал отвечать.

Журнал расходов. Пишется на каждый вызов, разбирается раз в неделю. Формат — JSONL: одна строка на запрос, никаких внешних сервисов.

# usage.py — обёртка, которая логирует каждый вызов
import json, time
from pathlib import Path
from config import client

LOG = Path("usage.jsonl")

def ask(prompt: str, model: str, max_tokens: int = 800, tag: str = "") -> str:
    r = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": prompt}],
        max_tokens=max_tokens,
    )
    with LOG.open("a", encoding="utf-8") as f:
        f.write(json.dumps({
            "ts": time.strftime("%Y-%m-%dT%H:%M:%S"),
            "model": model, "tag": tag,
            "in": r.usage.prompt_tokens, "out": r.usage.completion_tokens,
        }, ensure_ascii=False) + "\n")
    return r.choices[0].message.content
# budget_report.py — сводка за неделю, запускает аналитик команды
import json, collections
from pathlib import Path

rows = [json.loads(l) for l in Path("usage.jsonl").read_text(encoding="utf-8").splitlines() if l.strip()]
by_tag = collections.Counter()
by_model = collections.Counter()
for r in rows:
    by_tag[r.get("tag", "")] += r["in"] + r["out"]
    by_model[r["model"]] += r["in"] + r["out"]

total = sum(by_tag.values())
print(f"всего токенов: {total:,}".replace(",", " "))
for tag, n in by_tag.most_common(10):
    print(f"  {tag or 'без тега':28} {n:>10,}".replace(",", " ") + f"  {n/total:.0%}")
print("по моделям:", dict(by_model))

Алерты и поведение на порогах.

ПорогЧто делаемКто следит
50% лимитаРазбор журнала: какая работа съела половинуТимлид, на планёрке
80% лимитаТолько дешёвая модель, сильная — по письменному обоснованиюТимлид + наставник
100% лимитаСтоп. Локальная модель для рутины, заявка на расширениеНаставник

Локальный fallback ставится заранее, чтобы не искать его в день, когда ключ перестал отвечать:

ollama pull qwen2.5-coder:7b
ollama run qwen2.5-coder:7b "объясни ошибку numpy shape mismatch"

Почему персонализация уместна. Ключ один, а задачи разные: у T1 — оценка качества и интерфейс, у T2 — retrieval и разметка, у T3 — данные и продуктовая аналитика. Одинаковая инструкция заставила бы всех одинаково жечь бюджет. Ниже — три профиля по мотивационным письмам и строкам журнала практики.

T1 · Evidence — Участники 1–3Профиль использования ключа
Сильные стороныУчастник 1 — UX/CJM/HTML/React · Участник 2 — статистика и проверка гипотез · Участник 3 — pandas/sklearn/DuckDB и A/B
Что делают ключомКомпоненты интерфейса ассистента и тексты; разбор статистических ошибок и дизайна эксперимента; judge-скрипт и рубрика оценки
Модель по умолчаниюДешёвая: UI-правки, тексты, объяснения ошибок
Сильная модель — когдаПроектирование рубрики judge, спорный статистический вывод, архитектура оценки
Бюджет (ориентир)40% код и интерфейс · 35% оценка качества · 25% тексты и отчёт
Типовые промпты«Сгенерируй React-компонент по описанию, без новых зависимостей» · «Проверь корректность t-теста и его допущений» · «Оцени ответ по рубрике, верни JSON»
Главный рискМодель придумывает числа: все метрики считаются кодом, а не моделью

Участнику 2 — сильная модель на проверку статистики (цена ошибки в выводах выше цены токенов). Участнику 1 — дешёвая на итерации интерфейса: их много, они короткие.

T2 · Navigator — Участники 1–3Профиль использования ключа
Сильные стороныУчастник 1 — Python и полный цикл · Участник 2 — домен биологии и медицины · Участник 3 — Excel/SQL и дисциплина
Что делают ключомЧанкинг и retrieval по базе знаний, ответы с цитатами, батч-разметка карточек, проверка доменных формулировок
Модель по умолчаниюДешёвая: батч-разметка, извлечение полей, чанки
Сильная модель — когдаСхема ответа RAG, сложные вопросы, где retrieval дал противоречивые фрагменты
Бюджет (ориентир)50% батч-разметка · 30% генерация ответов · 20% отладка пайплайна
Типовые промпты«Извлеки 5 полей карточки в JSON» · «Ответь только по фрагментам, укажи id источников» · «Скажи, каких данных не хватает для ответа»
Главный рискПрогон всего корпуса дорогой моделью: сначала 20 карточек, замер качества, потом батч

Участник 3 ведёт usage.jsonl и недельный отчёт по бюджету — это его зона ответственности и хорошая учебная задача на SQL/pandas.

T3 · Analyst — Участники 1–3Профиль использования ключа
Сильные стороныУчастник 1 — продуктовый и системный анализ · Участник 2 — Python, baseline и метрики · Участник 3 — продукт, стартапы, исследование рынка
Что делают ключомГенерация pandas/SQL-кода, baseline-модели, сжатие статей и исследований, продуктовая часть отчёта
Модель по умолчаниюДешёвая: код, объяснения, черновики текстов
Сильная модель — когдаДизайн эксперимента, интерпретация метрик, спорная гипотеза
Бюджет (ориентир)40% код и модели · 30% исследование литературы · 30% отчёты
Типовые промпты«Сгенерируй pandas-код, объясни шаги, не выдумывай колонки» · «Сожми статью до 5 тезисов с числами и источником» · «Предложи 3 гипотезы с метрикой и способом проверки»
Главный рискПросить модель посчитать вместо запуска кода: числа берутся только из исполненного скрипта

Участникам 1 и 3 — дешёвая модель на черновики и структуру; участнику 2 — сильная на дизайн эксперимента, потому что он отвечает за воспроизводимость.

Общее для всех трёх команд. Ключ не выдаётся «на человека» — им пользуется команда через один .env. Это значит: договоритесь, кто и когда делает большие прогоны, чтобы двое не запустили один и тот же батч дважды. Простой способ — очередь в задачах репозитория и тег в usage.jsonl.

Что делаютЧем плохоКак правильно
Ключ в ноутбуке или в кодеПопадает в git и в историю навсегда.env + .gitignore, ключ читается через config.py
Ключ в общем чате командыУтечка не отслеживается, отзыв не помогаетПередача только хранителю, по защищённому каналу
«Скинь весь репозиторий в контекст»40–80 тыс. токенов на один вопросУказать 2–3 файла и задачу, остальное не нужно
Один запрос на 200 карточекОбрыв по max_tokens, потеря результата, повтор с нуляБатчи по 20–50 с кэшем и валидацией
Повторный прогон без кэшаОплата за те же данные дваждыКэш по хэшу входа
Верить числу из ответа моделиГаллюцинация выглядит как метрикаЧисла считает код; модель объясняет
Держать историю на 50 сообщенийКаждый шаг дороже предыдущего/compact, новая сессия на новую тему
Просить «сделай красиво»Три итерации впустую, результат не проверяемКритерий приёмки в промпте: формат, длина, что считаем успехом

Первые два пункта — про безопасность, остальные — про деньги. И то и другое восстанавливается дороже, чем предотвращается.

СимптомПричинаРешение
401 UnauthorizedКлюч неверный, отозван, с пробелом или кавычкамиПроверить .env без кавычек, перекопировать ключ, перевыпустить при отзыве
403 ForbiddenНет доступа к модели или ограничение по регионуСверить список моделей в кабинете, взять доступную
404 model not foundОпечатка в имени моделиСкопировать имя из /models
429 Too Many RequestsRate limit или исчерпан бюджет ключаПауза, меньший батч; при исчерпании — заявка наставнику
context_length_exceededПромпт больше окна моделиСократить контекст, разбить на части, retrieval вместо полного текста
Timeout / connection resetСеть, VPN, корпоративный проксиПроверить curl к /models, отключить VPN, повторить с timeout=60
CERTIFICATE_VERIFY_FAILEDПодмена сертификата прокси или антивирусом--trusted-host для pip, корневой сертификат организации, помощь наставника
Ответ на английском вместо русскогоПромпт без указания языкаЯвно: «ответь по-русски, 3–5 предложений»
Модель «не видит» файлФайл не передан в контекст, только упомянутПриложить содержимое или дать агенту прочитать путь

Правило трёх шагов: воспроизвести минимальным запросом → проверить /models → посмотреть usage. Если все три в порядке, проблема в промпте, а не в ключе.

Граница проходит по персональным данным. Всё, что уходит в API, покидает контур компании. Поэтому в промпты попадает только то, что разрешено передавать внешнему провайдеру.

Можно отправлятьНельзя отправлять
Публичные данные: BRFSS, NHANES, статьи, открытые датасетыСырые выгрузки NutriChat и Healora с идентификаторами
Обезличенные агрегаты: распределения, метрики, схемы таблицФИО, телефоны, почта, адреса, номера документов
Код, ошибки, конфиги без секретовМедицинские данные и жалобы конкретных пользователей
Черновики текстов отчёта и документацииКлючи API, пароли, токены, .env
Синтетические примеры, сгенерированные для тестаДанные партнёров под NDA

Сомневаетесь — не отправляйте и спросите наставника. Один вопрос дешевле инцидента с персональными данными.

  • ☐ Данные перед отправкой обезличиваются: id заменяются на хэши
  • ☐ Сырые выгрузки лежат вне git и не попадают в промпты целиком
  • ☐ В отчётах и презентациях нет ключей и персональных данных
  • ☐ Промпты и ответы, использованные в выводах, сохранены в docs/ai_log/
  • ☐ Ответственность за соблюдение — на тимлиде команды

Зачем хранить журнал промптов. Не для отчётности, а для воспроизводимости: через неделю никто не вспомнит, каким промптом получена метрика. Журнал — это доказательство метода на защите.

ДеньШагКтоРезультат
Д1Получить ключ, создать .env и .gitignoreТимлидКлюч вне git, файлы в репозитории
Д1Установить Python, openai, python-dotenvВсеpip list показывает пакеты
Д1Smoke-тест и запись в docs/ai_log/keys.mdТимлидСкриншот ответа и usage
Д2Настроить opencode.json, проверить агент на задачеТимлид + всеАгент читает файл и отвечает
Д2Включить usage.py в свои скриптыИнженер командыusage.jsonl пополняется
Д3Первый малый прогон (20 элементов) и замер стоимостиКомандаЦена на элемент известна
Д5Разбор журнала: где ушёл бюджетТимлидКорректировка на неделю 2
Д10Порог 50%: разбор и план экономииТимлид + наставникРешение по моделям
Д15Финал: отчёт, отзыв ключей, архивирование журналовТимлидКлючи отозваны, журнал в отчёте

Дни условные: отсчёт от 16.11. Главное — первые три шага в день 1, иначе неделя уходит на «настройку окружения».

Критерий готовности команды к неделе 1. Ключ работает, smoke-тест пройден, .env вне git, журнал расходов пишется, лимит и правило 80/20 зафиксированы в README команды. Всё остальное — детали, которые решаются по ходу.

  • OK
    16.11 09:00Инструкция собрана
    Три ключа — по одному на команду; профили T1/T2/T3 по мотивационным письмам; бюджет 80/20 и распределение 15/50/35 по неделям.
  • i
    16.11 09:00Плейсхолдеры вместо адреса API
    <BASE_URL> и <MODEL> берутся из кабинета: адрес и имена моделей зависят от тарифа и могут меняться.
  • !
    16.11 09:00Открытый вопрос
    Если сервис отдаёт не OpenAI-совместимый протокол — нужен отдельный коннектор и правка разделов 4–5.
↑