7. Модуль Alem

Генерация текста, потоковая передача, эмбеддинги, ранжирование и расшифровка аудио.

Модуль ALEM предоставляет доступ к моделям платформы Alem.Cloud. Модуль совместим с форматами OpenAI API и Anthropic Messages API, что позволяет применять официальные SDK указанных поставщиков с заменой базового адреса и ключа.

Модуль доступен по токену API, в котором указан модуль ALEM, и по токену доступа студента с областью доступа qairu.alem.read. В отличие от модулей данных, модуль ALEM принимает запросы методом POST по путям, перечисленным в настоящем разделе.

7.1. Подключение SDK

В качестве базового адреса SDK указывается адрес модуля, в качестве ключа — токен:

URL

https://api.bbx.kz/os/v1/alem

OpenAI SDK — параметр base_url (Python) или baseURL (JavaScript);
Anthropic SDK — тот же адрес; путь /v1/messages SDK добавляет самостоятельно.

7.2. Генерация текста

Генерация ответа выполняется запросом POST /os/v1/alem/chat/completions в формате OpenAI. Поддерживаются также операции POST /os/v1/alem/completions и POST /os/v1/alem/responses.

curl https://api.bbx.kz/os/v1/alem/chat/completions \
  -H "Authorization: Bearer qos_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V4.1-Flash",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Explain supervised learning in two sentences."}
    ],
    "max_tokens": 512
  }'

Запросы в формате Anthropic Messages API направляются по пути POST /os/v1/alem/v1/messages.

curl https://api.bbx.kz/os/v1/alem/v1/messages \
  -H "x-api-key: qos_YOUR_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V4.1-Flash",
    "max_tokens": 512,
    "messages": [
      {"role": "user", "content": "Explain supervised learning in two sentences."}
    ]
  }'

7.3. Потоковая передача

При значении параметра "stream": true ответ передаётся потоком событий text/event-stream по мере формирования. Поток в формате OpenAI завершается строкой data: [DONE]. Если клиент не задал параметр stream_options, в поток добавляется завершающий фрагмент со сведениями о расходе токенов usage; массив choices в этом фрагменте пуст.

curl -N https://api.bbx.kz/os/v1/alem/chat/completions \
  -H "Authorization: Bearer qos_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V4.1-Flash",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Write a short abstract about computer vision."}
    ]
  }'

7.4. Эмбеддинги

Векторные представления текстов возвращает запрос POST /os/v1/alem/embeddings. Параметр input принимает строку или массив строк.

curl https://api.bbx.kz/os/v1/alem/embeddings \
  -H "Authorization: Bearer qos_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "BAAI/bge-m3",
    "input": ["Neural networks", "Gradient descent"]
  }'

7.5. Ранжирование

Запрос POST /os/v1/alem/rerank упорядочивает документы по релевантности запросу. Формат запроса и ответа соответствует формату Cohere Rerank: ответ содержит массив results с номером документа index и оценкой релевантности relevance_score. Официальные SDK OpenAI и Anthropic эту операцию не поддерживают, поэтому запрос выполняется средствами HTTP-клиента.

curl https://api.bbx.kz/os/v1/alem/rerank \
  -H "Authorization: Bearer qos_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "BAAI/bge-reranker-v2-m3",
    "query": "How is the final grade calculated?",
    "documents": [
      "The final grade combines coursework and the examination.",
      "The library is open from 9 a.m. to 8 p.m.",
      "Coursework accounts for sixty percent of the final grade."
    ],
    "top_n": 2
  }'

7.6. Расшифровка аудиозаписей

Расшифровка выполняется запросом POST /os/v1/alem/audio/transcriptions в формате multipart/form-data. Поле file содержит аудиозапись, поле model — идентификатор модели распознавания речи. При значении response_format=verbose_json ответ дополнительно содержит фрагменты текста с временными метками. Размер файла не должен превышать 100 МБ.

curl https://api.bbx.kz/os/v1/alem/audio/transcriptions \
  -H "Authorization: Bearer qos_YOUR_TOKEN" \
  -F model=openai/whisper-large-v3 \
  -F response_format=verbose_json \
  -F file=@lecture.mp3

7.7. Отключение рассуждений

Отдельные модели перед ответом формируют рассуждение, расходующее лимит max_tokens. При малом значении max_tokens такая модель может вернуть пустое поле content с признаком "finish_reason": "length". Для отключения рассуждений в тело запроса добавляется параметр "chat_template_kwargs": {"enable_thinking": false}; в OpenAI SDK для Python он передаётся через extra_body. Часть моделей данный параметр не учитывает.

curl https://api.bbx.kz/os/v1/alem/chat/completions \
  -H "Authorization: Bearer qos_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V4.1-Flash",
    "messages": [{"role": "user", "content": "List three sorting algorithms."}],
    "max_tokens": 256,
    "chat_template_kwargs": {"enable_thinking": false}
  }'

7.8. Выбор модели и неподдерживаемые операции

параметр model обязателен для всех операций модуля; идентификаторы моделей следует получать из ответа GET /os/v1/alem/models;
запрос к модели, отсутствующей в перечне, отклоняется с кодом model_not_found; запрос к модели, не разрешённой токеном, — с кодом model_not_allowed;
генерация изображений, синтез речи, модерация, операции с файлами, векторными хранилищами и пакетными заданиями модулем не поддерживаются; запросы по таким путям отклоняются с кодом not_found;
ошибки обработки запроса моделью с кодами 400, 404, 413, 422 и 429 передаются клиенту без изменений; сбой или недоступность платформы Alem.Cloud возвращается ответом 502 с кодом upstream_error.

Перечень доступных моделей приведён в разделе «Перечень моделей».