GigaServe 🦜️🏓 = LangServe + GigaChat

GigaServe — это python-библиотека, которая позволяет размещать цепочки и runnable-интерфейсы GigaChain с предоставлением к ним доступа через REST API.

Библиотека GigaServe интегрирована с FastAPI и использует для валидации данных Pydantic.

Особенности библиотеки

Библиотека дает следующие возможности:

• Автоматическое определение схем ввода и вывода основе объекта GigaChain. Схемы применяются для каждого запроса к API и обеспечивают подробные сообщения об ошибках.
• Страница API-документации с JSONSchema и Swagger.
• Эндпоинты с поддержкой множества одновременных запросов на одном сервере
  /invoke
  ,
  /batch
  и
  /stream
  .
• Эндпоинт
  /stream_log
  для потоковой передачи всех или выбранных промежуточных шагов работы цепочки/агента.
• Интерактивная песочница
  /playground
  с потоковым отображением и демонстрацией промежуточных шагов.
• Использование проверенных open-source библиотек Python таких, как FastAPI, Pydantic, uvloop и asyncio.
• Клиентский SDK, который позволяет обращаться к серверу GigaServe также как к локальному runnable-интерфейсу или напрямую с помощью HTTP API.

Ограничения

• Колбэки клиента не поддерживаются для событий, происходящих на сервере.
• OpenAPI-спецификация не генерируется, если вы используете Pydantic V2. Это связанно с тем, что Fast API не поддерживает смешивание пространств имен pydantic v1 и v2. Подробнее в разделе ниже.

Установка {#ustanovka}

Для одновременной установки клиента и сервера используйте команду:

Вы можете установить клиент и сервер по отдельности с помощью команд:

GigaChain CLI 🛠️

GigaChain CLI — это утилита, которая поможет быстро настроить проект GigaServe. Для этого используйте следующую команду:

При работе с GigaChain CLI всегда используйте последнюю версию утилиты. Вы можете установить ее с помощью команды:

Примеры

Для быстрого старта GigaServe используйте шаблоны GigaChain.

Больше примеров шаблонов вы найдете в репозитории.

Сервер

Пример ниже разворачивает чат-модели GigaChat и других LLM, а также цепочку, которая генерирует шутку по заданной теме (

) с помощью модели Anthropic.

Документация

Сгенерированная OpenAPI-документация к серверу, развернутому с помощью предыдущего примера, доступна по адресу:

При этом, адрес

будет возвращать ошибку 404, пока вы не определите

@app.get("/")

.

Note

При использовании pydantic v2 документация не генерируется для эндпоинтов

/invoke

,

/batch

,

/stream

и

stream_log

.

Клиент

Пример клиента на основе Python SDK:

Пример клиента на TypeScript (для работы клиента требуется LangChain.js версии 0.0.166 или выше):

Клиент, использующий Python-библиотеку

:

Использование cURL:

Эндпоинты

С помощью примера ниже вы можете добавить на сервер заранее подготовленные эндпоинты для работы с runnable-интерфейсами:

Список эндпоинтов:

• POST /my_runnable/invoke
  — вызвать runnable-интерфейс для единичных входных данных;
• POST /my_runnable/batch
  — вызвать runnable-интерфейс для набора входных данных;
• POST /my_runnable/stream
  — вызвать для единичных входных данных с потоковым выводом;
• POST /my_runnable/stream_log
  — вызвать для единичных входных данных с потоковым выводом, включая вывод промежуточных шагов по ходу генерации;
• GET /my_runnable/input_schema
  — получить JSON-схему входных данных runnable-интерфейса;
• GET /my_runnable/output_schema
  — получить JSON-схему выходных данных runnable-интерфейса;
• GET /my_runnable/config_schema
  — получить JSON-схему параметров конфигурации runnable-интерфейса;

Note

Эндпоинты работают в соответствии с LangChain Expression Language interface (LCEL) — DSL для создания цепочек.

Песочница

Страница песочницы доступна по адресу

. На ней представлен простой интерфейс, который позволяет настроить параметры runnable-интерфейса и сделать запрос к нему с потоковым выводом и демонстрацией промежуточных шагов.

Виджеты

Песочница поддерживает виджеты и может использоваться для тестирования ваших цепочек с разными входными данными.

Кроме этого, если цепочка может настраиваться, песочница предоставляет задать параметры цепочки и поделиться ссылкой на полученную конфигурацию.

Обмен конфигурацией цепочки

In addition, for configurable runnables, the playground will allow you to configure the runnable and share a link with the configuration:

Работа с классическими цепочками

GigaServe работает как с runnable-интерфейсами (написанным с помощью LangChain Expression Language), так и с классическими цепочками (посредством наследования от

).

При работе с классическими цепочками учитывайте, что некоторые входные схемы для таких цепочек могут вызывать ошибки, т.к. могут быть некорректными или неполными. Такие ошибки можно предотвратить, если обновить атрибут

таких цепочек в GigaChain.

Развертывание

Ниже описаны способы развертывания на Google Cloud Platforms (GCP) и Azure.

Развертывание на GCP

Для развертывания на GCP Cloud Run используйте команду:

Развертывание на Azure

Вы можете развернуть сервер на Azure с помощью Azure Container Apps:

Подробная информация в официальной документации.

Работа с Pydantic

GigaServe поддерживает Pydantic v2 с некоторыми ограничениями:

• При использовании Pydantic v2 документация OpenAPI не генерируется. Это связанно с тем, что Fast API не поддерживает смешивание пространств имен pydantic v1 и v2.
• GigaChain использует пространство имен версии v1 в Pydantic v2.

За исключением указанных ограничений, эндпоинты API, страница песочницы и другие функции должны работать корректно.

Дополнительные возможности

Добавление аутентификации

О том, как добавить аутентификацию на свой сервер GigaServe — в разделах документации FastAPI, посвященных безопасности и использованию связующего ПО.

Работа с файлами

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

• Файл может быть загружен на сервер с помощью одного эндпоинта и обработан с помощью другого;
• Файл может быть представлен как в виде бинарного значения, так и в виде ссылки, например, на содержимое файла, размещенное в хранилище s3.
• Эндпоинт может быть блокирующим или неблокирующим.
• Сложную обработку можно выделить в отдельный пул процессов.

Выбирайте подход в соответствии со своими задачами.

Note

GigaServe не поддерживает тип

multipart/form-data

. Для загрузки бинарного значения файла в runnable-интерфейс используйте кодировку base64.

Пример загрузки файла закодированного с помощью base64.

Вы также можете загружать файлы с помощью ссылок (например, в хранилище s3) или загружать их на отдельный эндпоинт как

multipart/form-data

.

Настраиваемые типы входных и выходных данных

Типы входных и выходных данных определяются для всех runnable-интерфейсов. Они доступны в аттрибутах

и

output_schema

. GigaServe использует эти типы для валидации данных и генерации документации.

Вы можете переопределить наследованные типы с помощью метода

.

Общий пример работы с типами:

Пользовательские типы

Для десериализации данных в pydantic-модель, а не

, унаследуйтесь от

CustomUserType

. При наследовании от этого типа сервер не будет преобразовывать данные в

dict

, а будет сохранять их как pydantic-модель.

Note

Тип

CustomUserType

поддерживается только на стороне сервера и определяет поведение при декодировании данных.

Виджеты интерактивной страницы

На странице песочницы вы можете создавать различные виджеты, демонстрирующие работу runnable-интерфейсов вашего бекенда.

• Виджет задается на уровне поля и поставляется как часть JSON-схемы вводного типа.
• Виджет должен содержать ключ
  type
  , значением которого является один из известного списка виджетов.
• Другие ключи виджета будут связаны со значениями, описывающими пути в JSON-объекте.

Общая схема:

Виджет загрузки файла

Виджет позволяет загружать файлы в интерфейсе песочницы. Работает для файлов в виде base64-строки.

Фрагмент примера:

Note

Подробный пример загрузки файла.

Виджет чата {#vidzhet-chata}

Пример виджета в репозитории.

Чтобы задать виджет чата передайте

:

• Поле
  input
  — JSONPath к полю запроса, которое содержит новое входящее сообщение.
• Поле
  output
  — JSONPath к полю ответа, которое содержит одно или несколько сообщений.

Не указывайте эти поля, если входящие и исходящие данные должны быть представлены в исходном виде. Например, если нужно представить исходящие данные в виде списка сообщений.

Пример:

Включение и отключение эндпоинтов {#vklyuchenie-i-otklyuchenie-endpointov}

Начиная с версии GigaServe 0.0.33, можно включать и отключать открытые эндпоинты. Используйте атрибут

, если вы хотите предотвратить перезапись эндпонтов при обновлении версии библиотеки.

Пример ниже включает варианты эндпоинтов

,

batch

и

config_hash

.

Пример ниже отключает страницу песочницы для цепочки.

Безопасность

В версиях библиотеки 0.0.13—0.0.15 песочница, доступная по адресу

, позволяет получить доступ к произвольным файлам на сервере. Такое поведение исправлено в версии библиотеки 0.0.16 и выше.