Ассистенты (RAG)

Ассистент отвечает на вопросы по одной или нескольким вашим коллекциям. На каждом ходе он находит подходящие документы, передаёт их модели и возвращает ответ вместе с документами, на которых он основан. Это retrieval-augmented generation (RAG), который вы настраиваете, а не строите.

Ответ основан на найденных документах, поэтому он ровно настолько хорош, насколько хорош поиск: возвращённые источники — первое, что стоит проверить, если ответ выглядит неверным.

Создание и изменение ассистентов требует полного ключа. Задавать вопросы можно и с поисковым ключом из браузера (см. Из браузера). Для понимания запроса внутри обычного поиска вместо чата — разбор обычного языка в фильтры или цикл уточнений с вашей собственной моделью — см. поиск на естественном языке и модели диалога.

Создание ассистента

createAssistant — POST /assistants:

const assistant = await client.assistants.createAssistant({
  name: "Store help",
  system_prompt: "Ты помогаешь покупателям выбрать инструмент. Отвечай только по источникам.",
  collections: [
    {
      name: "products",
      query_by: "name,description",
      filter_by: "in_stock:true",
      k: 5,
      include_fields: "id,name,price,url",
    },
  ],
  max_sources: 6,
  retrieval_mode: "single",
});
// assistant.id — нужен для каждого вызова чата

listAssistants, getAssistant и deleteAssistant делают то, что следует из названий. updateAssistant (PUT /assistants/{assistantId}) принимает то же тело, что и создание, поэтому отправляйте конфигурацию целиком.

Вопрос

createChatCompletion — POST /assistants/{assistantId}/chat/completions:

curl -X POST "https://api.aacsearch.com/v1/assistants/$ASSISTANT_ID/chat/completions" \
  -H "X-NOVA-API-KEY: $NOVA_API_KEY" -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Какая дрель лучше для бетона?"}]}'

Запрос:

Ответ:

{
  "id": "…",
  "conversation_id": "…",
  "message": { "role": "assistant", "content": "Для бетона выберите ударную дрель [1] …" },
  "sources": [
    { "collection": "products", "document": { "id": "42", "name": "Ударная дрель, 18 В" }, "score": 0.91, "snippet": "…" }
  ],
  "usage": { "input_tokens": 1830, "output_tokens": 164 },
  "model": "@cf/meta/llama-3.3-70b-instruct-fp8-fast"
}

sources идут в том порядке, в каком их видела модель, поэтому [1], [2] в ответе указывают на sources[0], sources[1]. Показывайте их ссылками: именно они делают ответ проверяемым.

Ответ потоком

streamChatCompletion — POST /assistants/{assistantId}/chat/completions/stream — принимает то же тело и отвечает Server-Sent Events. Каждое событие — это ChatChunk с полем type:

const stream = await client.assistants.streamChatCompletion({
  assistantId: assistant.id,
  body: { messages: [{ role: "user", content: question }] },
});
let conversationId: string | undefined;
for await (const chunk of stream) {
  if (chunk.type === "delta") process.stdout.write(chunk.delta ?? "");
  if (chunk.type === "done") conversationId = chunk.conversation_id;
}

Диалоги

Передавайте conversation_id из предыдущего ответа (или из события done) со следующим ходом и только новое сообщение — историю ассистент загрузит сам. Диалог можно продолжать в течение memory_ttl_seconds после последнего обращения.

• getConversation — GET /assistants/{assistantId}/conversations/{conversationId} возвращает историю.
• deleteConversation — тот же путь с DELETE, например когда покупатель нажимает «начать заново».

Из браузера

createChatCompletion, streamChatCompletion, getConversation и deleteConversation доступны поисковой области, поэтому витрина вызывает их напрямую с поисковым ключом или короткоживущим браузерным ключом, который выпускает ваш сервер (см. ключи виджета). С поисковым ключом:

• X-NOVA-SESSION-ID обязателен (без него 400) — один id на вкладку браузера.
• Диалог принадлежит сессии, которая его начала; другая сессия получит 403.
• AI-вызовы ограничены на сессию посетителя; сверх лимита API отвечает 429, с Retry-After, когда известно, сколько ждать.

Чат поддержки aacsearch-ui и лёгкий виджет отправляют заголовок сессии сами.

Стоимость

Каждый ход оплачивается кредитами из кошелька организации по входящим и исходящим токенам, каким бы ключом ни был сделан запрос (см. кредиты). Если кошелёк не покрывает ход, API отвечает 402 с message, available и requested. Чтобы тратить меньше на ход, уменьшите max_sources или model.max_output_tokens, оставьте в include_fields только нужное для ответа и используйте retrieval_mode: "single".