Я создал ИИ-агента, который позволяет исследовать API на простом английском языке

В моем текущем продукте сотни API. Каждый раз, когда мне нужно обратиться к спецификации API, я должен перейти по ссылке Swagger, бесконечно прокручивать страницу или использовать поиск в браузере, чтобы найти то, что мне нужно, а затем вручную отфильтровывать результаты. Это раздражает и мучительно медленно. Еще хуже то, что каждый разработчик, которому нужно интегрироваться с API, должен пройти через тот же опыт.

Это разочарование побудило меня изучить, как ИИ мог бы улучшить процесс. Эта статья — глубокое погружение в этот путь и то, как он превратился во что-то простое, надежное и эффективное.

Подготовка

Подробная документация API

В качестве первого шага я просмотрел всю документацию API, чтобы убедиться, что в документации Swagger есть четкие сводки и подробные описания. Это критически важный шаг для лучшей обнаруживаемости на более поздних этапах. Я также убедился, что сводка и описание уникальны для каждого API.

paths": {     "/users/accounts/{account-id}": {       "put": {         "tags": [           "Account API"         ],         "summary": "Update Test suite by test-suite-id",         "externalDocs": {           "description": "Robust get account details description",           "url": "https://mydocs.com/description"         },

\

Категоризация API

С сотнями доступных API может быть сложно определить, какие из них связаны между собой. Категоризация API делает управление более эффективным и впоследствии упрощает выбор правильного API на основе ввода на естественном языке. Эта категоризация была реализована с использованием концепции тегов, определенной в спецификации OpenAPI.

\

"paths": {     "/users/accounts/{account-id}": {       "put": {         "tags": [           "Account API"         ],         "summary": "Update Test suite by test-suite-id",         "externalDocs": {           "description": "Robust get account details description",           "url": "https://mydocs.com/description"         },

\

Создание поиска на естественном языке

Пользовательский ввод

Пользователи вводят вопрос на естественном языке, связанный с API.

Пример: Как получить данные учетной записи?

Классификация категории

На этом этапе вопрос и все доступные категории отправляются в LLM. LLM должен вернуть высокоуровневую категорию, к которой относится вопрос. Результатом этого шага является одна из категорий.

Классификация конкретного API

На основе определенной LLM категории система отправляет еще один запрос модели с тем же вопросом — но на этот раз включает все детали API в рамках конкретной категории, обнаруженной на предыдущем шаге.

Здесь окупается ранее проведенная подготовка: чем более описательная и хорошо структурированная документация API, тем лучше результаты. Четкие описания помогают LLM точно определить, о каком API запрашивает информацию пользователь.

Результатом этого шага является один конкретный API.

Обогащение деталей ответа API

Спецификация OpenAPI затем предоставляется LLM для создания подробного, контекстно-богатого описания API вместе с исходным вопросом.

Например, если пользователь спрашивает: "Как я могу получить данные учетной записи, используя ID учетной записи?", ответ будет включать соответствующие детали спецификации API учетной записи.

Расширение

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

Например:

• "Поделитесь кодом Python для вызова API Get Account Details для данного ID."

• "Предоставьте команду cURL для получения данных учетной записи по ID."

• "Создайте клиент Go для получения данных учетной записи для конкретного ID."

\

Извлеченные уроки и выводы

• Подробная документация необходима для лучшей точности при работе с системами ИИ. Точная, ясная и конкретная документация необходима для надежности. Бонус: Мы также использовали LLM для создания сводки и описания для каждого API, что очень помогло.
• Сначала категоризируйте
• Почему: С сотнями API категоризация снижает когнитивную нагрузку и улучшает поиск.
• Как: Группируйте связанные API в небольшой набор четких категорий. Системы ИИ работают лучше, когда пространство меток ограничено.
• Совет по масштабированию: Если каталог очень большой, добавьте подкатегории для более точной маршрутизации.
• Создавайте итеративно
• Начните с малого: Возьмите подмножество спецификации и обучите/проверьте маршрутизатор, который может надежно выбирать правильный API.
• Расширяйтесь постепенно: Добавляйте больше API со временем, измеряйте точность и приоритизируйте области с неправильными классификациями.
• Фокус: Оптимизируйте точность/полноту, а не широту на начальном этапе.
• Замкните цикл с пользователями
• Собирайте отзывы: Фиксируйте случаи, когда система выбрала неправильный API.
• Действуйте на основе сигналов: Улучшайте описания, сводки и теги неправильно идентифицированных API; уточняйте перекрывающиеся области.
• Повторяйте: Переоценивайте после каждого изменения, чтобы подтвердить, что точность улучшается и регрессии избегаются.

Заключение

По мере роста числа доступных API, их изучение и управление требуют нового подхода. С появлением ИИ-агентов, работающих на основе больших языковых моделей (LLM), разработчики теперь имеют более интуитивный и эффективный способ обнаружения и взаимодействия с API, экономя бесчисленные часы, ранее потраченные на поиск правильных конечных точек.

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

Надеюсь, эта статья показала, как эффективно использовать LLM и как хорошо структурированная документация API может создать более плавный и интеллектуальный опыт обнаружения.

\n \n

\n \n