Разделы
Детально
Ключ API — это не «доступ к чату», а расходуемый ресурс с ценой за токен. На практику выдаётся три ключа — по одному на команду. Задача этой инструкции: поставить инструменты, подключить ключ так, чтобы он не утёк, и научиться тратить токены осознанно — чтобы к третьей неделе не остаться без бюджета на отчёт.
Порядок действий. (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-dotenv3. Клиент — на выбор. 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 · Evidence | HL-01…HL-02, MIPT-13: ассистент с цитатами, оценка качества | APICODE_API_KEY | Участник 3 · pandas, git | .env в корне репозитория команды |
| T2 · Navigator | MIPT-32, HL-03, HL-05: RAG по базе знаний, коннекторы | APICODE_API_KEY | Участник 1 · Python, git | .env в корне репозитория команды |
| T3 · Analyst | HAB-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 --version2. 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 tiktoken3. Терминальный агент. Если 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 → Endpoint | curl $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) | На что |
|---|---|---|---|
| Неделя 1 | 15% | 450 тыс. | Установка, smoke-тесты, разведка данных |
| Неделя 2 | 50% | 1.5 млн | Основная работа: код, батчи, RAG, эксперименты |
| Неделя 3 | 35% | 1.05 млн | Доводка, метрики, отчёт, подготовка защиты |
Резерв 10% внутри каждой недели — на отладку. Команда, потратившая 100% к среде, в четверг работает без модели.
Распределение по типам работ (ориентир, корректируется по задаче).
| Работа | Доля | Модель | Почему так |
|---|---|---|---|
| Код и правки | 40% | дешёвая | Много итераций, короткие ответы |
| Батч-обработка данных | 25% | дешёвая | Кэшируется, повторяемо |
| Оценка качества (judge) | 15% | средняя | Нужна устойчивость оценок |
| Архитектура, сложная отладка | 15% | сильная | Цена ошибки выше цены токенов |
| Тексты и отчёт | 5% | дешёвая | Черновик правится человеком |
Правило переключения: если задача формулируется как «объясни/поправь/перепиши» — дешёвая. Если «спроектируй/почему не работает/что здесь не так» — сильная.
Десять правил экономии.
- Одна задача — одна сессия. Новая тема — новый контекст.
- Не пересказывайте историю: сжимайте её (
/compact) или начинайте заново. max_tokensна выход: 512–1500 для рутины, больше — только осознанно.- Батч 20–50 элементов вместо 50 отдельных запросов.
- Кэш по хэшу входа: повторный вопрос не должен стоить денег.
- Сначала 20 примеров и замер качества — потом прогон на всём корпусе.
- Retrieval вместо «вот весь документ, найди сам».
- Черновики — дешёвой моделью, финальная версия — сильной, и только она.
- Журнал
usage.jsonlи разбор раз в неделю: где реально ушёл бюджет. - Алерты на 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 Requests | Rate 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 показывает пакеты |
| Д1 | Smoke-тест и запись в 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 команды. Всё остальное — детали, которые решаются по ходу.
- OK16.11 09:00Инструкция собранаТри ключа — по одному на команду; профили T1/T2/T3 по мотивационным письмам; бюджет 80/20 и распределение 15/50/35 по неделям.
- i16.11 09:00Плейсхолдеры вместо адреса API
<BASE_URL>и<MODEL>берутся из кабинета: адрес и имена моделей зависят от тарифа и могут меняться. - !16.11 09:00Открытый вопросЕсли сервис отдаёт не OpenAI-совместимый протокол — нужен отдельный коннектор и правка разделов 4–5.