Расширение xllm: вызовы LLM из скриптов

Обзор

34.1 Позиция и границы

xllm (vendored из extlibs xrt, базовый слой v3.0.0) забирает всю грязную работу «разговора с LLM-сервисами»:

• Три диалекта: Chat Completions (OpenAI-совместимый / GLM), OpenAI Responses, Anthropic Messages — один API запросов, проводной формат переключается перечислением eProvider
• SSE-стриминг: фреймизация, пересборка, инкрементальные колбэки; нестримовый режим — частный случай без колбэков
• Повторы и лимиты: повторяемые ошибки уходят в автоповтор с нарастающей паузой, Retry-After уважается; структура диагностики сообщает число попыток
• Отмена: встроена в систему отмены xrt (xcancel), плюс deadline на запрос

Границы столь же явные: она не исполняет инструменты (tool call возвращается вам — исполнение ваше дело) и не помнит историю диалога (каждый запрос лишён состояния; история и сжатие — забота верхних слоёв; xllm-session/xllm-memory из xrt в этот вариант не входят). Сеть, TLS, JSON и отмена — всё на встроенном xrt хоста; скрипт не линкует ни одного дополнительного рантайма.

34.2 Клиент и профили моделей

Первый шаг — всегда профиль модели: несекретный контракт возможностей — окно контекста, потолки входа/выхода, биты возможностей (вызовы инструментов, стриминг, ввод изображений…). Встроено семейство GLM, указатель заимствуется, профиль неизменяем:

xllm_error tErr;
const xllm_model_profile* pProfile;
xllm_client_config tConf;
xllm_client* pClient;

xllmErrorInit(&tErr);
pProfile = xllmModelProfileBuiltin("glm-5.2");      /* заимствуется, без копии */
if ( pProfile == NULL ) { /* имя с ошибкой: NULL */ ... }

xllmClientConfigInit(&tConf);                      /* все значения по умолчанию */
tConf.sBaseUrl      = "https://open.bigmodel.cn/api/paas/v4";
tConf.sApiKey       = getenv("XLLM_KEY");           /* заимствованный указатель! продакшн: Custom из xs.json */
tConf.sModel        = "glm-5.2";
tConf.eProvider     = XLLM_PROVIDER_GLM;
tConf.pModelProfile = pProfile;                     /* с профилем: проверка + снимок */
pClient = xllmClientCreate(&tConf, &tErr);          /* движком владеет библиотека */

Три момента: все строки заимствуются (библиотека их не копирует; время жизни должно перекрывать клиент); движок можно разделять (заполните pNetEngine двигателем хоста/приложения — несколько клиентов его разделят; NULL — библиотека владеет своим); профиль окупается втройне — согласованность конфигурации проверяется при создании, возможности проверяются перед каждым запросом (визуальный запрос текстовой модели будет отвергнут), а xllmModelProfileSupports(pProfile, XLLM_CAP_*) питает бизнес-ветвление.

34.3 Запросы и вызовы

Запрос — стековое значение; конструирование не касается сети. Сообщения четырёх ролей — system / user / assistant / tool; текст — одна API-функция, мультимодальность — через part:

xllm_request tReq;
char* sJson;

xllmRequestInit(&tReq);
xllmRequestSetModel(&tReq, "glm-5.2");
xllmRequestAddTextMessage(&tReq, XLLM_ROLE_SYSTEM, "Ты строгий помощник.");
xllmRequestAddTextMessage(&tReq, XLLM_ROLE_USER, "Расскажи про XServer одним предложением.");
printf("токены: %llu\n",
    (unsigned long long)xllmEstimateTextTokens("Расскажи про XServer одним предложением."));

sJson = xllmClientBuildRequestJson(pClient, &tReq, &tErr);
/* {"model":"glm-5.2","messages":[{"role":"system",...},...]} */
xllmFree(sJson);                                   /* всё, что выделила библиотека — xllmFree */
xllmRequestUnit(&tReq);

Два пути вызова: одношаговый xllmClientComplete (внутри повторы и пересборка потока; возвращает полный ответ); асинхронный xllmClientStart → заимствованный xfuture* → xllmCallWait / xllmCallCancel. Вызовы инструментов: на стороне запроса инструменты объявляются xllmRequestAddTool; на стороне ответа tool call попадает в бизнес-код, результат возвращается через xllmRequestAddToolResult — исполнение всегда остаётся у вас.

Типовое разделение в xs: колбэк HTTP-маршрута принимает запрос → Complete работает в фоновом потоке (дисциплина границ из гл. 41) → результат записывается назад. Блокирующий Complete нельзя запускать в колбэке рабочего потока движка.

34.4 Диалекты, стриминг и повторы

Стриминг: и xllmClientComplete/Start принимают xllm_stream_callbacks (приращения текста, рассуждений, вызовов инструментов, finish); NULL — нестримовый режим. Повторы управляются uMaxAttempts / uRetryBaseDelayMs / uRetryMaxDelayMs; при лимитах уважается Retry-After сервера. xllm_diagnostics в результате (число попыток, итоговая повторяемость) вместе с xllmErrorRetryable(&tErr) решает, ждать ли и пробовать снова на стороне бизнеса. Отмена двухканальная: на запрос — xllmRequestSetDeadline / SetCancel (xcancel), на вызов — xllmCallCancel.

34.5 Контракт

Потоки: клиент можно использовать из нескольких потоков (внутри пул соединений и блокировки), но один xllm_call не конкурентен; future — заимствованный, действителен до Wait/Destroy. Изоляция вариантов — по закону sqlite/xtp2: в варианте default нет <xllm.h> (ошибка «нет заголовка» на компиляции), скрипты проверяют #ifdef XS_USE_XLLM, вложенный TCC видит то же самое.

Частые ошибки

Упражнения