🔍 Анализ API-документации Groq AI: что нужно знать ДО старта интеграции 🔍

Прежде чем проектировать интеграцию с AI-сервисом — разбираемся с его API-документацией.
Без этого разработанные требования могут оказаться нереализуемыми.

Разбираем Groq API для проекта #MedAssistGA👇

✅ Документация
Главная страница
API Reference - основная документация для интеграции по API


✅ Вид API
REST API (JSON)
Поддерживается стриминг через SSE (Server-Sent Events)


✅ Авторизация и аутентификация
API Key
Передаётся в заголовке запроса:

Authorization: Bearer {api_key}

Ключ генерируется в консоли: console.groq.com/keys


✅ Тестовые доступы
✔ Есть бесплатный лимит запросов без привязки карты.
✔ Доступны все модели, ограничение только по rate limits


✅ Рекомендации по использованию
✔ Quickstart — как начать работать
✔ Prompting Guide — базовые и продвинутые рекомендации по разработке промптов
✔ Cookbooks — примеры использования
✔ Tool Use — поможет для разработки сценариев "AI вызывает медсистему"
✔ Production Checklist — отдельный раздел по подготовке системы к продакшн, включая безопасность


✅ Ограничения и особенности
✔ Rate limits по трём измерениям одновременно:
RPM — запросов в минуту
TPM — токенов в минуту
RPD — запросов в день

✔ Лимиты применяются на уровне организации (не пользователя)

✔ Срабатывает первый достигнутый лимит — не обязательно по токенам

✔ Кэшированные токены не учитываются в лимитах (актуально для системного промпта)

✔ Проверка лимитов аккаунта по ссылке


✅ Общие требования к обработке ошибок
Стандартные HTTP-коды, подробно описаны в разделе Error Codes.
При превышении rate limit (HTTP-429), в ответе заголовок retry-after — указывает, через сколько секунд повторить запрос.


✅ Список методов для нашей задачи

POST /chat/completions — основной метод диалога с ИИ (текстовый ответ)

✔ stream: true — стриминг ответа через SSE
✔ Tool Use (Local Tool Calling) — механизм вызова AI-агентом инструментов нашей системы: расписание, список врачей, запись, уведомления

👉 Других методов для сценария записи к врачу не потребуется.


Результат этого первичного анализа — основа для исследовательского тестирования API в Postman и постановки задач разработчикам 📝✅


#ИнтеграцииGA

📱 GetAnalyst | 💙 VK | 💬 Max

🏥 Архитектура #MedAssistGA: что важно понимать для интеграции с AI-платформами 🏥

На схеме показана часть архитектуры медицинской системы, связанная с интеграцией с Groq для реализации AI-чат-бота.
Выбрали микросервисный подход.


Что важно:

👉 Взаимодействие с нейросетью
Groq не вызывает наши сервисы напрямую, когда нужно получить список врачей или записать пациента на приём.

Схема работы такая:

1. Сервис AI-чата отправляет запрос в Groq

2. Когда для ответа нужны данные из системы, Groq возвращает не просто текст, а команду (tool call) — «вызови этот инструмент с этими параметрами»

3. Сервис AI-чата сам выполняет вызов нужного сервиса и возвращает результат обратно в Groq

4. Groq формирует финальный ответ пациенту

Инструменты (tools), которые может запросить ИИ:
▫️ Сервис Врачей — список специалистов и специализаций
▫️ Сервис Расписаний и Записей — доступные слоты, создание записи

Сервис AI-чата — не просто прокси между пользователем и Groq.
Это оркестратор, который управляет циклом: запрос → tool call → вызов сервиса → ответ в модель → следующий шаг.


👉 Защита данных: что намеренно не передаём в AI-чат
Персональные данные пациента в Сервис AI-чата не передаются.

Детальный профиль, история болезней и другие ПДн — вне доступа нейросети. Это осознанное архитектурное решение, хотя вопрос ещё будем обсуждать при проектировании сценариев.


👉 Уведомления через Kafka
Два источника событий уходят в брокер асинхронно, чтобы отправлять уведомления пользователям:
▫️ Сервис расписаний и записей → при создании записи на приём
▫️ Сервис AI-чата → при отправке исходящих сообщений чата


👉 RAG - обучение AI
В проектах, где AI работает на собственных данных компании (база знаний, документы, история обращений), в архитектуру добавляют RAG-слой:
векторная БД + компонент поиска по ней.

Нейросеть ищет релевантный контекст перед ответом.

В текущей версии RAG нет.
AI получает данные через tool calls к API системы.
Но когда выйдем за рамки записи к врачу и захотим отвечать на любые вопросы пациентов — RAG станет следующим шагом.


💡 Рекомендация
Один из первых вопросов при проектировании AI-интеграции — что вообще имеет право знать нейросеть.

Это не технический вопрос, это требование.

Аналитик фиксирует его явно: разрешённые tool calls, передаваемые данные, история чата по токену.


👉 Зачем это знать аналитику
AI-интеграция — это не только промпты и нейросети.

Это архитектурные решения:
+ какие сервисы вызывает AI,
+ что ему разрешено знать,
+ как данные движутся через систему,
+ и где проходит граница между “можно” и “нельзя”.

Именно поэтому AI-интеграция проектируется не вокруг модели, а вокруг доступа к данным.



P.S.
А вообще, в идеале, желательно разворачивать свою локальную LLM для проекта, а не пользоваться публичным Groq.
Но у нас открытая практика, так что можно 😉


#ИнтеграцииGA #АрхитектураGA

📱 GetAnalyst | 💙 VK | 💬 Max

💡🤖 Use Case: Запись к врачу через AI-чат #MedAssistGA 🏥💡

Разбираемся в порядке работы AI-чата для сети поликлиник, который помогает подбирать врачей и записывать на приём по диагнозу пользователя.


👉 Цель:
Пациент получает рекомендацию специалиста и записывается на приём


👉 Роли:
Пользователь-пациент


👉 Предусловие:
Пользователь открыл чат и нажал «Записаться к врачу»


👉 Основной сценарий:

1. AI-чат приветствует и просит описать симптомы

2. Пользователь описывает симптомы

3. Сервис AI-чата отправляет запрос в Groq AI.
Groq AI анализирует симптомы и возвращает предварительный диагноз

4. AI-чат показывает пользователю краткий диагноз и уточняет симптомы.

5. Пользователь подтверждает диагноз или уточняет симптомы новым сообщением.

6. Сервис AI-чата отправляет запрос в Groq AI.

7. Groq AI анализирует диагноз и возвращает:
▫️ уточненный диагноз (возврат к шагу 5),
▫️ специализацию врача в соответствии со справочником MedAssistGA, которого надо посетить при данном диагнозе в первую очередь (tool call).

8. Сервис AI-чата определяет город пользователя:
▫️ если авторизован → берёт из настроек аккаунта
▫️ если не авторизован → определяет по IP
▫️ если IP не определился → просит пользователя выбрать город вручную из справочника

9. Сервис AI-чата вызывает Сервис Врачей:
запрашивает список специалистов рекомендованной специализации в городе пользователя.

10. Сервис AI-чата вызывает Сервис Расписаний:
запрашивает историю визитов пользователя к врачам.

11. Сервис AI-чата формирует список врачей по правилам приоритета:
▫️ сначала — врачи, которых пользователь уже посещал,
▫️ затем — врачи из клиник, в которых пользователь уже бывал,
▫️ далее — остальные специалисты по специализации,
Внутри каждой группы врачи отсортированы по рейтингу по убыванию.
Если история посещений недоступна или пользователь не авторизован — показываем всех врачей по рейтингу в городе.

12. Сервис AI-чата запрашивает ближайший свободный слот для первых 5 врачей из списка.
Если у кого-то из них нет доступных слотов — система последовательно перебирает следующих врачей из списка до тех пор, пока не наберётся 5 врачей с доступными слотами в соответствии со срочностью.

13. AI-чат показывает список из 5 врачей с указанием:
+ клиник сети, в которых они принимают,
+ рейтинга,
+ времени ближайшего приёма.

14. Пользователь может:
👉 14.1. Кнопка или текст: Выбрать врача, чтобы продолжить запись.
14.2. Кнопка: Перейти к просмотру карточки врача и его отзывов.
14.3. Кнопка или текст: Запросить больше карточек врачей, если предложенные не подходят.
14.4. Текст: Сообщить AI-чату, что хочет добавить подробности и уточнить диагноз.
14.5. Текст: Попросить AI-чат найти самый ближайший слот к любому врачу.
14.6. Текст: Попросить AI-чат найти врачей, которые принимают в определенный период.
14.7. Текст: Уточнить город.

15. Сервис AI-чата вызывает Сервис Расписаний:
запрашивает доступные слоты выбранного врача по всем клиникам в городе пользователя.

16. Пользователь может:
16.1. Кнопка или текст: выбрать дату и время для записи,
16.2. Кнопка или текст: запросить даты и время в расписании, которые не показаны.

17. Система проверяет авторизацию пользователя.
Если пользователь не авторизован, то внутри чата открывается окно для авторизации / регистрации в системе.

18. AI-чат показывает карточку подтверждения с деталями записи и кнопкой «Подтвердить» в интерфейсе чата

19. Пользователь нажимает «Подтвердить»

20. Сервис AI-чата выполняет вызов Сервиса Расписаний:
создаёт запись на приём.

21. Пользователь получает подтверждение записи в чате, sms и email уведомления о записи.


👉 Альтернативные сценарии:

🔻 На каждом шаге пользователь может ввести сообщение в AI-чат, которое не относится к записи на приём.
AI-чат отвечает: "Извините, я не могу помочь с этим вопросом"



Это основной сценарий работы пользователя, который далее будем наполнять техническими деталями интеграции с AI 🙌


Вопросы или уточнения по сценарию?
Делитесь в комментариях💡


#ИнтеграцииGA #AI_for_analysts

📱 GetAnalyst | 💙 VK | 💬 Max

Когда слишком серьезно подошел к задаче «показывать понятный текст ошибки от backend» 🥲

📱 GetAnalyst | 💙 VK | 💬 Max

🤖 10 особенностей работы с AI-интеграциями 🤖

AI-интеграции отличаются от обычных.

Тут другая логика, другие риски и другие вопросы от разработчиков.

Разбираю 10 особенностей, которые важно понимать аналитику.


1️⃣ Недетерминированность
AI не возвращает один и тот же ответ на один и тот же запрос.
Нужно явно описывать как система ведёт себя при разных ответах.


2️⃣ Стриминг вместо одного ответа
Ответ может приходить потоком сообщений через SSE.
Это отдельные требования к фронту, бэку и обработке обрывов соединения.


3️⃣ Ограниченный контекст (context window)
Длинный диалог может «выпасть» из памяти модели.
Нужны требования к хранению и передаче истории диалога.



4️⃣ AI сам инициирует вызовы вашего API (Tool Calling)
Не только ваша система вызывает API AI.
AI тоже вызывает ваш API через tools (инструменты), которые вы ему даёте.

Для каждого tool нужно описать:
▫️ название инструмента
▫️ назначение
▫️ входные параметры
▫️ обязательные поля
▫️ ограничения
▫️ возможные ошибки
▫️ какой сервис реально вызывается на backend
▫️ что возвращается обратно в модель



5️⃣ Системный промпт
Это тоже требование.
Его нужно проектировать, документировать, согласовывать и версионировать.

Включает:
▫️ правила поведения AI
▫️ ограничения
▫️ формат ответа
▫️ примеры корректных ответов
▫️ запрещённые действия
▫️ что делать при нехватке данных



6️⃣ Граница «что видит ИИ»: требования к безопасности
Это одно из главных требований, особенно если система работает с:
+ персональными, медицинскими или финансовыми данными
+ коммерческой тайной
+ внутренними документами компании

Аналитик должен зафиксировать:
▫️ какие данные разрешено / запрещено передавать
▫️ нужно ли маскирование / обезличивание
▫️ хранится ли история диалога
▫️ кто имеет доступ к логам AI



7️⃣ Непредсказуемые входные данные
Пользователь может написать что угодно.
Нужны явные требования: как система реагирует на вопросы не по теме, оскорбления, попытки сломать или украсть системный промпт.



8️⃣ Rate limits и стоимость
В отличие от большинства внешних API, у LLM-провайдеров ограничения идут сразу по трём измерениям одновременно:
▫️ RPM — запросов в минуту
▫️ TPM — токенов в минуту
▫️ RPD — запросов в день
Срабатывает первый достигнутый лимит — не обязательно по токенам.

Поэтому в требованиях нужно зафиксировать:
▫️ поведение при HTTP-429
▫️ использование заголовка retry-after — через сколько секунд повторить запрос
▫️ нужен ли rate limiting на стороне нашего бэкенда
▫️ fallback — что делает система, если лимит исчерпан надолго



9️⃣ Логирование диалогов
Чтобы разобрать инцидент «почему AI дал такой ответ», нужно знать:
▫️ какой системный prompt был активен
▫️ какие данные попали в контекст модели
▫️ что написал пользователь
▫️ какие tool calls запросила модель
▫️ какие внутренние сервисы были вызваны
▫️ что модель вернула на каждом шаге
▫️ какой финальный ответ получил пользователь
Без этого разбор инцидентов превращается в гадание.

Дополнительно фиксируем:
▫️ как долго хранятся логи и кто имеет доступ
▫️ нужно ли маскировать ПДн в логах
▫️ логи хранятся на стороне провайдера или только у нас

В медицине это ещё и регуляторный вопрос: история переписки пациента с AI может приравниваться к медицинской документации со всеми вытекающими требованиями к хранению и доступу.



🔟 Agentic loop — цепочка tool calls
AI может сделать несколько вызовов подряд.
Нужна логика остановки, таймаутов и обработки ошибок в цепочке — иначе бесконечный цикл станет сюрпризом на проде.


Сохраняйте, пригодится на задачах с AI-интеграциями 🤝

#ИнтеграцииGA #AI_for_analysts

📱 GetAnalyst | 💙 VK | 💬 Max

💥 Интеграции — это понимание того, как система работает “под капотом” 💥

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

И это было ОК! 😃


А потом пришёл "умный и важный" Backend-разработчик и сказал примерно так:

Теперь мы делаем не монолит, где UI + логика + БД в одной кодовой базе.
Теперь у нас Frontend и Backend, которые общаются по API.

И вот тогда я впервые узнала интеграции на минимальном уровне:
➡️ Frontend → Backend


Но настоящий "аттракцион" начался позже, когда появилась задача получать данные из внешней системы 👀

➡️ наш Frontend → наш Backend → внешняя система
➡️ а потом интеграции микросервисов


👉 И самое неприятное тогда было — чувство, когда ты угадываешь, что ждут разработчики...
Было много "танцев на граблях".

С годами интеграций становилось больше: разные API, протоколы, асинхрон, оборудование. И этот тип задач в итоге стал моим самым любимым 🩷

Сейчас я рада делиться своим опытом в интеграциях с вами в GetAnalyst!



Мы открыли предзапись на новый поток практической программы для СА и БА, который проводим в новом летнем формате:

💥💥💥 Интеграции систем

⚪ с 8 июля до 23 сентября — обучение по записям в комфортном вам темпе
🟢 30 сентября — закрытая онлайн-встреча по подготовке к собеседованиям
🟢 с 14 октября до 23 декабря — можете подключиться к онлайн-занятиям и работать с экспертами


🎁🎁🎁 До 3 июля — самый большой набор бонусов за всю историю GetAnalyst:

✅ Расширенный доступ
8/12 месяцев вместо стандартных 6/9

✅ Курс «БД и SQL: продвинутый уровень»
в подарок (обычная стоимость 9 500 руб) — поможет для работы с маппингом

✅ Мини-курс «REST API для аналитиков 3.0»
больше по проектированию API с нуля после основного обучения

🟢 Онлайн-встреча по подготовке к собеседованиям 30 сентября
решаете задачи с реальных интервью в прямом эфире и получаете обратную связь


Результат:

✔️ Описываете интеграционные Use Cases
✔️ Уверенно работаете с API: REST, SOAP, GraphQL, gRPC, WebSocket
✔️ Опыт работы с Postman
✔️ Знаете нотацию C4 для архитектуры
✔️ Понимате асинхрон, в т.ч. брокеры
✔️ Можете сделать задачу на интеграционный REST API метод
✔️ У вас десятки примеров документации, которые можно переиспользовать в работе

Это то, что сейчас спрашивают Middle+ системных аналитиков на собеседованиях, и то, что реально нужно в работе.


💥 Интеграции систем
🔗 Узнать подробнее и записаться


Приглашаем вас получить за лето навык, который даёт уверенность и рост в карьере СА, как раз к периоду активного осеннего найма 🍁🙌


Вопросы? Пишите @getanalyst или info@getanalyst.ru.
Уточним ваш опыт и подскажем, подойдёт ли вам программа 🤝

🧡 10 гайдов по Postman, которые прокачают работу с API 🧡

Документация ≠ реальность.

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

Он заранее уточняет нюансы, которых нет в API-документации внешней системы, чтобы разработчики затем не тратили на это время.


Что важно проверить аналитику при исследовании API:
✅ как работает аутентификация
✅ как выполняются нужные API-методы
✅ какие параметры обязательны
✅ какие поля приходят в JSON-ответе
✅ какие ошибки возвращаются при нештатных ситуациях
✅ как API ведёт себя при некорректных данных, отсутствии доступа или пустом результате


👉 Делюсь подборкой практических руководств по исследованию API внешних систем через Postman:

📹 Postman: навык тестирования REST API за вечер

📚 Тестирование API DaData

📚 Тестирование API Unisender

📚 Тестирование API банка ВТБ

📚 Тестирование API KudaGo и DashaMail

📚 Тестирование API ChatGPT

📚 Практика с настройкой OAuth 2.0 от Mail ru

📚 7 видов аутентификации в API - демо с настройками в Postman

📹 Аутентификация mTLS на практике в Postman

📚 GraphQL API — знакомство на практике Postman


👉 В этих руководствах всё по шагам: с картинками, настройками запросов и примерами.

С ними можно за выходные освоить базовую работу в Postman и пополнить портфолио несколькими коллекциями API-запросов 🙌



🔖 Сохраняйте пост в избранное,
чтобы пройти все руководства и получить реальный опыт в API для работы с задачами на интеграции


#ИнтеграцииGA

📱 GetAnalyst | 💙 VK | 💬 Max