Forge: Надежный слой для вызова инструментов LLM

В эпоху, когда локальные большие языковые модели (LLM) становятся все более доступными и мощными, разработчики сталкиваются с новой, неочевидной проблемой: надежность. Запустить модель на своем GPU — это лишь половина дела. Настоящий вызов начинается, когда вы просите модель использовать инструменты (tools) — выполнять вычисления, искать в интернете или управлять файлами. Маленькие модели (особенно в диапазоне 8 миллиардов параметров) часто «галлюцинируют» в формате вывода, путаются в синтаксисе JSON или просто забывают вызвать нужный инструмент. Это делает их использование в продакшене рискованным.

На сцену выходит Forge — библиотека, которая позиционирует себя не как полноценный оркестратор агентов, а как слой надежности (reliability layer). Ее главная задача — взять сырой вывод от локальной модели и превратить его в структурированный, валидированный и безопасный вызов инструмента. Forge не заменяет ваш агентный фреймворк; он встраивается в него, работая как фильтр и корректор, повышая точность вызовов инструментов с единичных процентов до 84% для локальных моделей и до 98% для флагманских решений вроде Sonnet 4.6.

В этой статье мы подробно разберем, как работает Forge, какие три режима использования он предлагает, как настроить бэкенды (от Ollama до vLLM) и почему этот инструмент может стать стандартом для локального запуска AI-агентов в России и мире.

01Что такое Forge и зачем он нужен?

Forge — это надстройка над локальными LLM, которая обеспечивает стабильность вызова инструментов (tool-calling). Если вы используете модели типа Mistral, Llama или Ministral, вы наверняка сталкивались с тем, что модель выдает инструмент в неправильном формате: например, оборачивает JSON в markdown-блоки, использует нестандартные теги или просто игнорирует часть аргументов. Forge перехватывает эти ошибки на лету.

Ключевая философия проекта: структура рабочего процесса (workflow) опциональна. Вы можете использовать Forge без жестких сценариев, просто включив «защитные ограждения» (guardrails). Эти ограждения включают:

• Rescue parsing (спасательное парсинг): если модель выдала инструмент в формате Mistral ([TOOL_CALLS]name{args}) или Qwen (<tool_code>), Forge извлекает данные и приводит их к стандарту OpenAI.
• Retry nudges (подталкивания к повторной попытке): если валидация провалена, Forge не просто возвращает ошибку, а отправляет модели корректирующее сообщение, объясняя, что пошло не так, и просит повторить попытку.
• Response validation (валидация ответа): проверка каждого вызова инструмента на соответствие описанию схемы (Pydantic) до того, как ответ вернется клиенту.

Это позволяет использовать Forge даже с самыми простыми сценариями, где модель просто должна выбрать один из доступных инструментов, не следуя сложному графу зависимостей.

02Три способа интеграции Forge

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

1. Proxy Server (Прокси-сервер)

Это самый популярный и простой способ начать работу. Forge запускается как прокси-сервер, который встает между вашим клиентом (например, IDE-плагином или CLI-инструментом) и локальным бэкендом модели. Прокси поддерживает оба основных API: OpenAI Chat Completions и Anthropic Messages.

Зачем это нужно? Вы можете направить существующие инструменты, такие как opencode, Continue, aider или Cline, на локальную модель через прокси Forge. Для этих клиентов Forge выглядит как «умная» версия модели. Они не знают, что за кулисами происходит валидация, исправление формата и повторные попытки. Это позволяет добавить надежность к любому OpenAI-совместимому клиенту без переписывания кода.

Также поддерживается Claude Code. Если вы настроите переменные окружения ANTHROPIC_BASE_URL и ANTHROPIC_AUTH_TOKEN на адрес прокси, вы сможете использовать локальную модель с интерфейсом Claude Code, получая при этом все преимущества защиты от ошибок.

2. WorkflowRunner (Запускатель рабочих процессов)

Если вам нужен полный контроль над логикой агента, используйте WorkflowRunner. В этом режиме вы определяете инструменты, выбираете бэкенд и запускаете структурированные циклы агентов. Forge управляет полным жизненным циклом: от системных промптов до исполнения инструментов, сжатия контекста и применения защитных ограждений.

Этот режим идеален, когда вам нужно задать жесткие правила: какие шаги обязательны (required_steps), какие инструменты являются финальными (terminal_tool) и в каком порядке они должны вызываться. Это мощный инструмент для создания детерминированных агентов, где важна последовательность действий.

3. SlotWorker (Рабочий слот)

Для продвинутых архитектур, где несколько агентов или специализированных рабочих процессов делят один GPU, Forge предлагает SlotWorker. Он обеспечивает доступ к общему вычислительному слоту с приоритетной очередью и автоматическим прерыванием (auto-preemption). Это позволяет эффективно использовать ресурсы GPU в многоагентных системах, где разные задачи конкурируют за вычислительную мощность.

03Настройка бэкендов: от Ollama до vLLM

Forge не запускает модели сам по себе; он требует работающего LLM-бэкенда. Поддерживается широкий спектр решений, что позволяет выбрать оптимальный вариант под ваше железо.

llama-server (Рекомендуемый вариант)

Это серверная часть библиотеки llama.cpp. Она обеспечивает наилучшую производительность и поддержку всех функций Forge, включая нативный вызов инструментов (Native Function Calling). Для запуска потребуется скачать бинарный файл с официального репозитория и запустить сервер с нужной моделью. Пример команды:

llama-server -m path/to/Ministral-3-8B-Instruct-2512-Q8_0.gguf --jinja -ngl 999 --port 8080

Важно использовать флаг --jinja для корректной обработки шаблонов промптов, необходимых для некоторых моделей.

Ollama

Самый простой вариант для новичков. Ollama берет на себя управление моделями и загрузку. Однако на сложных задачах (hard workloads) он может показывать чуть более низкие результаты по сравнению с llama-server. Установка и запуск:

ollama pull ministral-3:8b-instruct-2512-q4_K_M

vLLM

Идеален для высокопроизводительного обслуживания (high-throughput serving) и работы с весами форматов AWQ/GPTQ. vLLM поддерживает нативный вызов инструментов на стороне сервера. Для использования в режиме Managed (когда Forge сам запускает бэкенд) используйте флаг --backend vllm и укажите путь к модели.

Anthropic

Forge также поддерживает API Anthropic как бэкенд. Это полезно для гибридных рабочих процессов, где часть логики выполняется на локальной модели, а часть — на мощных моделях Anthropic. Для этого потребуется установить пакет forge-guardrails[anthropic] и задать ключ API.

04Глубокое погружение: Как работает Proxy Mode

Режим прокси (Proxy Mode) — это «фишка» Forge, которая делает его таким удобным для интеграции. Давайте разберем, что именно происходит с каждым запросом POST /v1/chat/completions, проходящим через прокси.

Forge применяет стек защитных мер в строгом порядке:

1. Response Validation: Forge проверяет каждый вызов инструмента в ответе модели. Если модель называет несуществующий инструмент или передает аргументы неверного типа, ошибка фиксируется.
2. Rescue Parsing: Если формат вывода нестандартен (например, JSON в блоке кода или специфичные теги Mistral/Qwen), Forge извлекает структуру и преобразует ее в канонический формат OpenAI tool_calls. Это критически важно для моделей семейства Mistral, которые часто используют свои собственные форматы.
3. Retry Loop: Если валидация провалена, Forge не возвращает ошибку клиенту. Вместо этого он отправляет модели корректирующее сообщение с результатом ошибки и просит повторить попытку. Это происходит до --max-retries раз (по умолчанию 3). Для клиента это выглядит как один запрос, который просто занял чуть больше времени.
4. Synthetic Respond Tool: Когда в запросе есть инструменты, Forge внедряет специальный синтетический инструмент respond. Модель должна вызвать его вместо того, чтобы просто вывести текст. Этот вызов затем «strips» (удаляется) из исходящего ответа. Клиент видит обычный текстовый ответ с finish_reason: "stop" и никогда не узнает, что использовался инструмент. Это необходимо для маленьких локальных моделей (~8B), которые часто путаются в выборе между генерацией текста и вызовом инструмента.

Важно отметить, что Proxy Mode работает в режиме «single-shot» для каждого запроса. Он не управляет историей диалога (context compaction) и не enforcing-ит порядок шагов (prerequisite enforcement), так как эти функции требуют состояния между запросами, которое не передается в стандартном API OpenAI. Для этих функций нужен WorkflowRunner.

05Пример кода: Запуск WorkflowRunner

Если вы хотите использовать Forge в своем Python-коде для создания агентов с полной логикой, вот пример использования WorkflowRunner. Этот код определяет инструмент для получения погоды, настраивает клиента (в данном случае Llamafile, но можно использовать и другие) и запускает рабочий процесс.

import asyncio
from pydantic import BaseModel, Field
from forge import Workflow, ToolDef, ToolSpec, WorkflowRunner, LlamafileClient, ContextManager, TieredCompact

def get_weather(city: str) -> str:
    return f"72°F and sunny in {city}"

class GetWeatherParams(BaseModel):
    city: str = Field(description="City name")

workflow = Workflow(
    name="weather",
    description="Look up weather for a city.",
    tools={
        "get_weather": ToolDef(
            spec=ToolSpec(
                name="get_weather",
                description="Get current weather",
                parameters=GetWeatherParams
            ),
            callable=get_weather
        ),
    },
    required_steps=[],
    terminal_tool="get_weather",
    system_prompt_template="You are a helpful assistant. Use the available tools to answer the user."
)

async def main():
    client = LlamafileClient(
        gguf_path="path/to/Ministral-3-8B-Instruct-2512-Q8_0.gguf",
        mode="native",
        recommended_sampling=True
    )
    ctx = ContextManager(
        strategy=TieredCompact(keep_recent=10),
        budget_tokens=8192
    )
    runner = WorkflowRunner(
        client=client,
        context_manager=ctx
    )
    await runner.run(workflow, "What's the weather in Paris?")

asyncio.run(main())

В этом примере мы видим, как просто определить инструмент с помощью Pydantic-модели и связать его с реальной функцией. WorkflowRunner берет на себя управление контекстом (сжатие истории сообщений через TieredCompact) и выполнение цикла агента.

06Оценка эффективности: От единичных цифр к 98%

Одной из главных причин создания Forge стала проблема низкой надежности локальных моделей. В оценочном наборе данных (eval suite) v0.7.0, состоящем из 26 сценариев, локальная модель размером 8B без Forge показывала результаты в «единичных процентах» на сложных задачах. После применения защитных ограждений Forge этот показатель вырос до 84%.

Для сравнения, флагманская модель Sonnet 4.6 от Anthropic без дополнительных слоев надежности показывала 85%, а с использованием Forge — 98%. Это демонстрирует, что Forge не только спасает локальные модели, но и значительно повышает качество работы даже передовых коммерческих решений, устраняя технические ошибки в формате вывода.

Оценочный набор включает базовый уровень OG-18 и продвинутый уровень advanced_reasoning из 8 сценариев, который тестирует способность модели к сложным рассуждениям и многошаговым вызовам инструментов. Запустить оценку можно с помощью встроенных скриптов:

python -m tests.eval.eval_runner --backend llamafile --llamafile-mode prompt --gguf path/to/model.gguf --runs 10 --stream --verbose

07Установка и развертывание в Docker

Для тех, кто предпочитает контейнеризацию, Forge поддерживает запуск в Docker. Это упрощает развертывание прокси-сервера в производственной среде.

Сначала соберите образ:

docker build -t forge-proxy

Затем запустите контейнер, подключившись к внешнему бэкенду (например, vLLM, работающему на хост-машине). Обратите внимание на использование host.docker.internal для macOS/Windows, чтобы контейнер мог найти бэкенд:

docker run -p 8081:8081 forge-proxy --backend-url http://host.docker.internal:8000 --backend vllm --budget-mode manual --budget-tokens 8192

Это позволяет легко интегрировать Forge в существующие инфраструктуры, где модели уже запущены в отдельных контейнерах или на выделенных серверах.

08Что это значит на практике

Для разработчиков, работающих с локальными LLM в России, где доступ к некоторым облачным API может быть ограничен или дорог, Forge становится критически важным инструментом. Он позволяет:

• Повысить надежность: Перестать бояться, что агент сломается из-за неверного JSON в ответе модели.
• Использовать существующие инструменты: Подключить к локальным моделям такие популярные инструменты, как Continue, Aider или Claude Code, без необходимости писать сложные обертки.
• Экономить ресурсы: За счет сжатия контекста и эффективного управления токенами в режиме прокси можно дольше удерживать диалог в рамках лимитов VRAM.
• Масштабировать: Использовать SlotWorker для распределения нагрузки между несколькими агентами на одном GPU.

Forge не пытается заменить оркестраторы вроде LangChain или AutoGen. Он занимает нишу «клея», который делает взаимодействие между клиентом и моделью надежным. Если вы строите агентов на локальных моделях, особенно в диапазоне 8B, интеграция Forge может стать тем самым шагом, который превратит эксперимент в работающий продукт.

09Заключение

Forge — это мощный, но специализированный инструмент. Он не для всех, но для тех, кто строит серьезные агенты на локальных моделях, он становится незаменимым. Его фокус на надежности, простота интеграции через прокси и поддержка широкого спектра бэкендов делают его одним из самых перспективных проектов в экосистеме локальных LLM. С открытым исходным кодом и MIT-лицензией, Forge доступен каждому, кто хочет сделать свои AI-решения более устойчивыми.

Источник: Hacker News ↗