TypeScript SDK: Ai: анализ и преобразование
ctx.ai() вызывается через платформу и расходует AI-бюджет пространства, кроме подтверждённого попадания extract() в кэш. Все методы асинхронны. Модель выбирает платформа: сценарий задаёт уровень и усилие.
Примеры — отдельные фрагменты тела async function run(ctx: Akmelo.Context): Promise<void>. Используйте await только для методов с Promise в сигнатуре.
Перед первым вызовом
- За один прогон доступно не более восьми AI-вызовов. В один запрос передавайте не более 48 КБ. Если страница большая, сначала выберите нужный фрагмент обычными методами SDK.
- Запрос расходует AI-бюджет пространства. Фактический расход отражается в лимитах и журнале операций; время выполнения сценария учитывается отдельно. Проверенный кэш
extract()позволяет повторно использовать правило без нового AI-вызова. - Не передавайте в запрос пароли, токены и персональные данные. Не отправляйте туда результат
ctx.credential(). - Автономный агент не может выполнить AI-запрос без платформы. Для регулярного автономного сбора сохраняйте уже проверенные правила в коде.
Уровень и усилие
| Параметр | Значения | Когда использовать |
|---|---|---|
tier |
small, medium, large |
От короткой записи до сложного анализа или исправления кода. |
effort |
low, medium, high, extra_high |
Чем выше усилие, тем больше времени и токенов может потребоваться. |
По умолчанию используются small и medium. Для repair() — large и high. Платформа сама выбирает подходящую модель; название модели в сценарии указывать не нужно.
Методы
analyze
ctx.ai().analyze(content, question, tier, effort) → Promise<string>
Отвечает текстом на вопрос о переданном содержимом. Ответ может ошибаться: проверяйте факты перед сохранением данных.
const result = await ctx.ai().analyze('sku,price\nA-1,1250', 'Где цена?');
transform
ctx.ai().transform(data, shape, instruction, tier, effort) → Promise<object>
Преобразует объект под указанную структуру и возвращает сам результат как объект. Проверяйте обязательные поля перед ctx.emit().
const result = await ctx.ai().transform({ title: 'Товар', price: '1 250 ₽' }, { title: 'string', price: 'number' });
find
ctx.ai().find(html, description, tier, effort) → Promise<{ selector: string, reason: string }>
Предлагает CSS-селектор элемента по переданному HTML и описанию. Возвращает selector и reason; проверяйте селектор на странице.
const result = await ctx.ai().find('<button class="next">Далее</button>', 'Кнопка следующей страницы');
repair
ctx.ai().repair(source, error, goal, tier, effort) → Promise<string>
Возвращает предложение по исправлению переданного TypeScript-кода. Не сохраняет его и не публикует новую версию. Проверьте ответ и сделайте пробный прогон.
const result = await ctx.ai().repair('async function run(ctx: Akmelo.Context): Promise<void> {}', 'Элемент не найден', 'Собрать название товара');
documentRows
ctx.ai().documentRows(document, sheet) → Promise<object>
Планирует строки и заголовок таблицы по форме ячеек, без раскрытия значений внешней модели. Вернёт ready, needs_range или incomplete; в двух последних случаях задайте диапазон вручную.
const document = await ctx.documents().fromUrl(ctx.param<string>('file_url'), 'prices.csv');
const result = await ctx.ai().documentRows(document, 0);
if (result.status === 'ready') {
for (const row of result.records) ctx.emit(row);
}
extract
ctx.ai().extract(input, schema, options) → Promise<object>
Извлекает записи из одной HTML-таблицы, JSON-массива, массива строк или одного листа документа. CSV сначала прочитайте через documents().fromBytes() или sources().document(). PDF без таблицы и произвольные карточки страницы нужно предварительно преобразовать в строки.
const result = await ctx.ai().extract(
[['Артикул', 'Цена'], ['A-1', '1 250,50']],
{ sku: { type: 'string', unique: true }, price: { type: 'decimal', min: 0 } },
{ key: 'supplier-prices', expected_rows: 1 },
);
for (const record of result.records) ctx.emit(record, String(record.sku));
records содержит данные текущего запуска, даже если правило найдено в кэше. Поля cache_hit и ai_used помогают понять, был ли запрос к модели. Для явного сопоставления можно указать column у полей и header_row в настройках; индексы начинаются с нуля. При неоднозначном заголовке проверьте выбор колонок вручную.
Если сервис недоступен или вернул неверный ответ, SDK выдаёт ошибку. Предложенный селектор, преобразование или исправление кода всегда проверяйте пробным прогоном, прежде чем публиковать сценарий.