Реалізація Function Calling (Tool Use) для AI-асистента у мобільному додатку

Реалізація Function Calling (Tool Use) для AI-асистента у мобільному додатку

Function Calling—це механізм, при якому модель не намагається сама відповісти на запитання «яка погода завтра», а повертає структурований JSON з описанням того, що потрібно викликати: {"name": "get_weather", "arguments": {"city": "Мінськ", "date": "tomorrow"}}. Додаток виконує виклик, передає результат назад, і модель формує фінальну ответ. У OpenAI це tools, у Anthropic—tool_use, у Google—function_calling.

Де реально ломиться на мобільному

Найчастіша проблема—неправильно описані JSON Schema для інструментів. Модель вибирає інструмент на основі опису та схеми параметрів. Якщо схема розмита («передай що потрібно»), модель либо не викликає інструмент взагалі, либо передає параметри в неправильному типі. Конкретний кейс: поле amount описане як string замість number—модель передає "150", десеріалізатор очікує Double, додаток крашиться з JsonDataCorruptedException. Gson та Moshi за замовчуванням не конвертують рядок у число молчки.

Друге вузьке місце—паралельні виклики інструментів. GPT-4 та Claude 3 можуть повернути декілька tool_calls в одному ответі. Якщо обробляти їх послідовно, користувач чекає. На Android правильно—async/await через корутини (async { } + awaitAll()), на iOS—async let або TaskGroup. Важливо: всі результати потрібно повернути моделі в одному messages[] кроці з role: "tool" для кожного виклику—OpenAI вимагає саме це, інакше 400 Invalid request.

Третя проблема—нескінчений цикл викликів. Якщо інструмент повернув помилку, модель іноді намагається викликати його знову з тими ж параметрами. Обмежуйте кількість ітерацій (5–10 звичайно достатньо) та передавайте помилку явно у вмісту ответу—це допомагає моделі перемкнутися на іншу стратегію.

Архітектура ToolDispatcher

// Android—диспетчер інструментів
class ToolDispatcher {
    private val tools = mapOf<String, suspend (JsonObject) -> String>(
        "get_weather" to ::handleGetWeather,
        "search_flights" to ::handleSearchFlights,
        "book_hotel" to ::handleBookHotel
    )

    suspend fun dispatch(toolName: String, args: JsonObject): String {
        return tools[toolName]?.invoke(args)
            ?: """{"error": "unknown tool: $toolName"}"""
    }
}

Кожен обробник повертає String (JSON-рядок результату). Модель отримує текст, не об'єкт—це принципово. Не потрібно серіалізовувати складні структури; достатньо зрозумілого JSON з ключовими даними.

Опис інструментів повинен бути максимально конкретним:

{
  "name": "search_products",
  "description": "Шукає товари у каталозі за назвою або категорією. Використовуй коли користувач питає про конкретний товар або хоче подивитися ассортимент.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": {"type": "string", "description": "Поисковой запит на мові користувача"},
      "category": {"type": "string", "enum": ["electronics", "clothing", "food"]},
      "limit": {"type": "integer", "default": 10, "maximum": 50}
    },
    "required": ["query"]
  }
}

Поле description впливає на те, викличе ли модель інструмент. «Пошук»—погане описання. «Шукає товари у каталозі, коли користувач називає конкретний продукт»—модель розуміє контекст застосування.

Управління станом діалогу на клієнті

Function Calling вимагає зберігання повної історії повідомлень: user → assistant (з tool_calls) → tool (результат) → assistant (фінальна ответ). На мобільному—правильна модель даних для Message:

// iOS
enum MessageRole { case user, assistant, tool }
struct Message: Codable {
    let role: MessageRole
    let content: String?
    let toolCalls: [ToolCall]?   // тільки для role == .assistant
    let toolCallId: String?      // тільки для role == .tool
    let name: String?            // ім'я інструмента для role == .tool
}

Зберігайте всю цепочку у @State / ViewModel. Якщо обрізати історію для економії токенів, обрізайте тільки ранні user/assistant пари, але ніколи не обрізайте незавершений цикл виклику інструмента—модель отримає помилку контексту.

Етапи та сроки

Аналіз бізнес-логіки та опис інструментів → реалізація ToolDispatcher та JSON Schema → інтеграція у діаловий цикл → обробка паралельних викликів → тестування граничних випадків (невідомий інструмент, помилка API, таймаут) → моніторинг.

Інтеграція Function Calling для 3–5 інструментів: 2–3 тижні. З розширеною логікою, паралельними викликами та складним управлінням станом—4–6 тижнів.