Кошелёк и AI-кредиты
Как работает предоплаченный кошелёк для AI — пополнения, автозачисление, лимиты расходов, записи реестра и возвраты.
AACsearch разделяет биллинг плана и AI-расход. Планы платят за поисковую ёмкость и места; кошелёк платит за AI-функции. Кошелёк — предоплаченный баланс в микро-USD (или копейках для RUB-клиентов), списываемый per-AI-вызов.
Кошелёк независим от плана, имеет свой реестр и не переносится из месяца в месяц, но и не сгорает. Баланс лежит, пока не потратите.
Зачем вообще кошелёк?
AI-стоимость прыгает per-вызов. Типичный RAG-запрос — несколько тысяч токенов; длинный ретрив с rerank — десятки тысяч. Зашить эту волатильность в плоский cap плана = либо огромные планы (переплата для большинства), либо постоянный сюрприз-overage. Предоплаченный кошелёк делает стоимость per-call видимой и счёт — предсказуемым.
За что платит кошелёк
| Функция | Списывается с кошелька? | Замечания |
|---|---|---|
POST /search | Нет | Обычный поиск тратит search units плана, не кошелёк. |
| AI rerank | Да | Добавляет rerank-запись на каждый поиск с rerank. |
| Knowledge-запрос (RAG) | Да | Embeddings + LLM-токены per-запрос. |
/embeddings | Да | Только-embedding вызовы (например, вы строите свой RAG). |
| Суммаризация документа | Да | Один вызов на summary. |
| AI-чат | Да | По токенам per-ход, кумулятивно на истории. |
| Реиндекс | Нет | Только search units — AI не вызывается. |
Функции плана (поиск, ингест, коннекторы, аналитика) никогда не списывают с кошелька. AI только через кошелёк.
Жизненный цикл
пополнение → баланс растёт → AI-вызов → запись списания → баланс падает → пополнение …В любой момент у кошелька:
balance: BigInt— текущий баланс в микро-USD/копейках.currency: "USD" | "RUB"— фиксирована при первом пополнении.autoRechargeEnabled: boolean— если true, автопополнение при пороге.autoRechargeThreshold: BigInt— триггер.autoRechargeAmount: BigInt— сумма автозачисления.spendingLimit: BigInt | null— опциональный per-period cap.
Схема — WalletAccount и WalletLedgerEntry.
Пополнение
Из /settings/billing/ai-credits:
- Top up.
- Сумма ($10 / $50 / $200 или кастом).
- Подтвердить сохранённым способом оплаты.
- Кошелёк пополняется как только пришёл вебхук провайдера (обычно секунды).
Чек уходит на биллинг-email. Запись реестра: type: "topup" с брутто-суммой.
Если есть сохранённый VAT/ИНН, чек его включит. Иначе заполните Billing details до пополнения.
Автозачисление
Если не хотите думать о пополнениях, включите автозачисление. /settings/billing/ai-credits → Auto-recharge:
- Enabled.
- Threshold (баланс ниже — срабатывает).
- Amount (сколько добавить).
Когда баланс пересекает порог сверху вниз, запускается автопополнение с сохранённым способом оплаты. Сбои — retry с backoff. После трёх подряд автозачисление паузится, придёт email.
Для защиты от runaway-расходов задавайте месячный spending limit рядом. Автозачисление уважает лимит — выше cap не пополняет.
Spending limits
Лимит расходов капит, сколько кошелёк может списать за календарный месяц. При достижении AI-вызовы падают с wallet_spending_limit_reached, автозачисление паузится.
Из /settings/billing/ai-credits → Spending limit:
- Задайте месячный cap (любое положительное число).
- Опционально — пороги 50%, 80%, 100% — присылают email.
Лимит сбрасывается 1-го числа каждого месяца в 00:00:00 UTC.
Записи реестра
Каждая операция кошелька пишет в WalletLedgerEntry:
| Поле | Значение |
|---|---|
id | Стабильный ID |
walletId | Какой кошелёк |
type | topup, embedding, rerank, knowledge, summarize, chat, refund, admin_adjust |
amount | BigInt микро-USD, со знаком (плюс = credit, минус = debit) |
balanceAfter | Снапшот баланса после записи (для аудита) |
referenceId | Внешний ключ на исходное событие (search id, knowledge id, top-up id) |
metadata | Модель, количество токенов, ключи сырых ответов провайдера |
createdAt | Когда записано |
Полный реестр экспортируется из /settings/billing/ai-credits → Export (CSV) или v1 REST:
curl https://app.aacsearch.com/api/v1/wallet/ledger?from=2025-01-01&to=2025-01-31 \
-H "Authorization: Bearer $AACSEARCH_ADMIN_KEY"Правила ценообразования
AI-цены не плоские — зависят от модели и провайдера. Таблица правил публикуется в /settings/billing/ai-credits → Pricing:
| Операция | Модель | Единица | Цена (USD) |
|---|---|---|---|
| Embedding | text-embed-3 | за 1k токенов | $0,0001 |
| LLM (knowledge) | claude-haiku | за 1k input токенов | $0,0008 |
| LLM (knowledge) | claude-haiku | за 1k output токенов | $0,004 |
| Rerank | cohere-rerank | за 1k токенов | $0,001 |
Ставки могут меняться с 30-дневным уведомлением — об увеличении придёт email. Уменьшения — сразу.
Частые ошибки
| Статус | Код | Значение |
|---|---|---|
| 402 | wallet_balance_insufficient | Баланс ниже минимально нужного для вызова. |
| 402 | wallet_spending_limit_reached | Достигнут месячный лимит. |
| 402 | wallet_currency_mismatch | Валюта кошелька отличается от валюты цены. |
| 402 | wallet_disabled | Кошелёк отключён администратором (редко; обратитесь в поддержку). |
| 503 | pricing_provider_unavailable | Не смогли узнать ставку; вызов отклонён, списания нет. |
Это 402 (Payment Required), а не 429 — кошелёк это soft-state, не rate limit. Пополните и повторите.
Возвраты
Возвраты — в двух случаях:
- Возврат пополнения — chargeback или запрос через поддержку. Атомарно реверсим и платёж, и запись реестра (запись
type: "refund"с отрицательной суммой = пополнению). - Операционная корректировка — платформенный админ выдаёт кредит (например, баг биллинга).
type: "admin_adjust"с положительной суммой и причиной вmetadata.
Баланс кошелька никогда не уходит в минус. Если возврат сделал бы это — поддержка свяжется для согласования.
Мульти-валюта
Кошелёк — single-currency на всё время жизни. Валюта фиксируется при первом пополнении — USD и RUB в одном кошельке не смешать.
Для смены валюты (переход юр.лица EU → RU) — тикет в поддержку. Старый закрывается возвратом до нуля, открывается новый в целевой валюте.
Override администратора
Платформенный админ может корректировать любой кошелёк из /admin/wallet:
- Вручную кредит или дебет (аудит-логируется с причиной).
- Полный реестр по всем org.
- Отключение кошелька (блокирует все AI).
- Перевыпуск проваленного пополнения.
Действия аудита: wallet_admin_adjust, wallet_disable, wallet_enable.
Связанные страницы
- Планы — что покрывает план (поиск), что — кошелёк (AI).
- Единицы потребления — полный справочник, включая AI-события.
- Квоты — планы; механика капов кошелька описана тут.
- Счета — чеки пополнения vs счета плана.