Перейти к основному содержимому

Создание локальных ИИ-агентов

Продвинутый

Локальный ИИ-агент — это автономный цикл, который работает полностью на вашем собственном оборудовании: модель с открытыми весами (обслуживаемая через Ollama или LM Studio) решает, что делать, вызывает инструменты, которые вы ей даёте, читает результаты и продолжает, пока задача не будет выполнена — причём ничто не покидает вашу машину. Никакого облачного API, никаких счетов за каждый вызов, никакого интернета. Подвох: модель, достаточно маленькая, чтобы работать на ноутбуке, слабее в сложных рассуждениях и долгосрочном планировании, чем передовая модель, а её надёжность и безопасность лежат на вас. Эта страница разбирает честные аргументы в пользу локальных агентов, минимальную архитектуру, что на самом деле работает локально, и реалистичный путь к вашему первому агенту.

What you'll learn
  • Понять, ПОЧЕМУ стоит строить агента, работающего локально — и честные компромиссы по сравнению с агентом на облачном API
  • Разобраться в минимальной архитектуре: локальная модель + цикл вызова инструментов + инструменты + ограничитель/условие остановки
  • Выбрать локальную модель, которая действительно способна на использование инструментов / агентную работу
  • Знать, какие агентные фреймворки работают локально, если направить их на локальную конечную точку (LangGraph, CrewAI, OpenAI Agents SDK)
  • Пройти путь «начни с простого» — от одиночного вызова инструмента до цикла с ограничителями
  • Изолировать агента в песочнице и ограничить его бюджет, чтобы автономный цикл не мог нанести реальный ущерб

Зачем строить локального агента (и когда не стоит)​

Обычный агент с использованием инструментов вызывает облачную модель. Локальный агент заменяет этот облачный вызов моделью, работающей на вашей собственной машине. Вы жертвуете частью возможностей и берёте на себя часть операционной нагрузки; взамен вы получаете четыре вещи, которые трудно получить каким-либо другим способом:

  • Приватность — промпты, входные данные инструментов и их выходные данные никогда не покидают машину. Именно ради этого команды в регулируемых, чувствительных или изолированных (air-gapped) средах строят локальных агентов: данные физически не могут попасть к третьей стороне.
  • Офлайн — никакого интернета, никакой зависимости от API, никаких сбоев провайдера. Агент — это файлы на вашем диске; он работает в самолёте или за фаерволом.
  • Отсутствие оплаты за вызов — цикл агента может делать десятки вызовов модели на одну задачу. Локально эти вызовы «бесплатны» (вы платите электричеством и оборудованием, а не токенами), так что можно позволить ему итерировать, не глядя на счётчик.
  • Полный контроль — зафиксировать точную версию модели, настроить поведение и работать без лимитов запросов или сюрпризов в условиях использования.

Честные компромиссы — трезво оцените их, прежде чем решаться:

  • Разрыв в возможностях. Самая сложная часть агента — это рассуждения: планирование многошаговой работы, восстановление после неудачного вызова инструмента, понимание, когда остановиться. Модель, которую можно запустить на ноутбуке (примерно 1B–14B параметров), здесь заметно слабее передовой модели. Простые, чётко очерченные циклы хорошо работают локально; долгосрочные, открытые задачи — это как раз то, где локальные агенты чаще всего сходят с рельсов.
  • Надёжность и безопасность на вас. Никакой провайдер не фильтрует, не мониторит и не ставит ограничители за вас. Если агент зациклится навсегда, вызовет не тот инструмент или совершит разрушительное действие — это на вашей совести как разработчика. (См. предупреждение ниже — именно эту часть люди недооценивают.)
  • Ограничения оборудования. Более крупным, более умным моделям нужно больше RAM/VRAM, чем есть у большинства машин. Обычно вы выбираете самую крупную способную модель, которую тянет ваше оборудование, а не лучшую модель, что вообще существует.

Устойчивое правило: начинай локально, эскалируй, когда задача этого требует. Используйте локального агента для приватной/офлайн/дешёвой-в-масштабе работы и чётко очерченных циклов; тянитесь к агенту на передовом API, когда задаче действительно нужны дополнительные рассуждения. Архитектура ниже одинакова в обоих случаях — меняется только конечная точка — так что вы можете прототипировать локально и заменить модель позже.

Минимальная архитектура​

Разберите агента до сути — и вы найдёте четыре части. Всё остальное — удобства поверх них.

        ┌─────────────────────────────────────────────┐
        │                                             │
        │   1. LOCAL MODEL  ──►  decides next action  │
        │      (Ollama / LM Studio, tool-capable)     │
        │                  │                          │
        │                  ▼                          │
        │   2. TOOL-CALLING LOOP                       │
        │      parse the model's tool request,         │
        │      run it, feed the result back            │
        │                  │                          │
        │                  ▼                          │
        │   3. TOOLS  ──►  search / read file /        │
        │      run code / call an API (your code)      │
        │                  │                          │
        │                  ▼                          │
        │   4. GUARDRAIL / STOP CONDITION              │
        │      max steps, budget, approval gate,       │
        │      "done" check ──► exit the loop          │
        │                                             │
        └─────────────────────────────────────────────┘
  1. Локальная модель, поддерживающая вызов инструментов. Модель должна уметь выдавать структурированный запрос на вызов инструмента (он же function calling), а не просто болтать. Ollama предоставляет это через свой API и через OpenAI-совместимую конечную точку по адресу http://localhost:11434/v1, так что любой фреймворк, говорящий на формате OpenAI, может управлять локальной моделью.
  2. Цикл вызова инструментов. Сердце агента: отправить разговор модели, посмотреть, не попросила ли она вызвать инструмент, выполнить этот инструмент, добавить результат и повторить. Когда модель отвечает без запроса инструмента, цикл заканчивается.
  3. Инструменты. Обычные функции, которые вы предоставляете модели — поиск в вебе, чтение файла, запуск shell-команды, запрос к базе данных, обращение к API. У каждого инструмента есть имя, описание и типизированная схема входных данных, чтобы модель знала, когда и как его использовать.
  4. Ограничитель / условие остановки. Не подлежит обсуждению для автономии. Как минимум — лимит максимального числа шагов, чтобы цикл не мог работать вечно, плюс — для всего, что пишет, удаляет, тратит или отправляет — шлюз подтверждения или песочница. Без этого у вас не агент, а бесконечный цикл с доступом к файлам.

Цикл в шаге 2 действительно маленький. Вот он в псевдокоде на Python против локальной конечной точки Ollama:

Минимальный цикл локального агента (псевдокод на Python, указывает на локальный Ollama)

from openai import OpenAI

# Point the OpenAI client at your LOCAL Ollama endpoint — nothing leaves the machine
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

tools = [{
  "type": "function",
  "function": {
      "name": "read_file",
      "description": "Read a UTF-8 text file and return its contents",
      "parameters": {
          "type": "object",
          "properties": {"path": {"type": "string"}},
          "required": ["path"],
      },
  },
}]

def run_tool(name, args):
  if name == "read_file":
      # GUARDRAIL: only allow reads inside a sandboxed directory
      return safe_read(args["path"])
  raise ValueError(f"unknown tool: {name}")

messages = [{"role": "user", "content": "Summarize ./notes/today.md"}]

for step in range(8):                       # GUARDRAIL: hard step cap
  resp = client.chat.completions.create(
      model="llama3.1", messages=messages, tools=tools,
  )
  msg = resp.choices[0].message
  messages.append(msg)

  if not msg.tool_calls:                  # STOP: model answered, we're done
      print(msg.content)
      break

  for call in msg.tool_calls:
      result = run_tool(call.function.name, json.loads(call.function.arguments))
      messages.append({
          "role": "tool", "tool_call_id": call.id, "content": str(result),
      })
else:
  print("Stopped: hit the step cap without finishing.")

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

Какие локальные модели подходят для агентной работы / использования инструментов​

Не всякая модель с открытыми весами может управлять агентом. Планка — это надёжный вызов инструментов: модель должна стабильно выдавать корректно сформированные запросы инструментов, выбирать правильный инструмент и не галлюцинировать аргументы. Два фильтра при выборе:

  • Это должна быть модель, способная к инструментам. Ollama помечает такие — просматривайте категорию Tools для актуального списка, а не полагайтесь на догадки. Среди моделей, которые часто называют для надёжного локального использования инструментов, — семейства инструктированных моделей Qwen и Llama; точный лучший выбор меняется от квартала к кварталу.
  • Она должна помещаться в ваше оборудование с запасом под контекст. Циклы агента накапливают длинные истории сообщений (каждый результат инструмента добавляется), так что вам нужны и веса, и щедрое окно контекста в памяти. Меньшая модель, которая комфортно помещается и работает быстро, часто выигрывает у более крупной, которая свопится на диск и застревает посреди цикла.

Решающий ход — не чтение бенчмарков, а запуск небольшого eval вашей задачи против двух-трёх кандидатов-моделей. Модель, возглавляющая лидерборд, всё равно может быть ненадёжной на конкретных инструментах, которые нужны вашему агенту. Измеряйте на своём собственном цикле.

Фреймворки, работающие локально​

Вы можете написать цикл выше вручную, и для первого агента это отличный способ научиться. Для чего-либо серьёзного фреймворк даёт вам повторные попытки, память, координацию нескольких агентов и трассировку. Ключевой факт: популярные агентные фреймворки не зависят от модели — им безразлично, находится ли модель в облаке или на localhost, лишь бы вы направили их на правильную конечную точку.

  • LangGraph — низкоуровневый фреймворк оркестрации для агентов с состоянием (устойчивое выполнение, персистентность, human-in-the-loop). Не зависит от модели; подключите его к локальной модели через интеграцию LangChain Ollama без обходных путей. Хорош, когда вам нужен явный контроль над графом состояний агента.
  • CrewAI — более высокоуровневый фреймворк для оркестрации одного или нескольких ролевых агентов («экипажей»). Не зависит от модели через LiteLLM; направьте агента на локальную модель с помощью LLM(model="ollama/llama3.1", base_url="http://localhost:11434"). Хорош, когда вы хотите быстро составить несколько сотрудничающих агентов.
  • OpenAI Agents SDK — лёгкий мультиагентный фреймворк. Несмотря на название, он не зависит от провайдера: через свою интеграцию LiteLLM вы можете направить его на локальную модель Ollama вместо модели OpenAI. Хорош, когда вам нужна эргономика агентов OpenAI на локальном бэкенде.

Выберите один фреймворк и изучите его хорошо, а не пробуйте все три. Концепции (агенты, инструменты, циклы, состояние) переносятся; API — это детали.

Соберите своего первого локального агента​

Реалистичный путь идёт от «вообще без цикла» до «автономного цикла с ограничителями» продуманными шагами. Не перескакивайте к шагу 4 — большинство неудач, с которыми люди сталкиваются с локальными агентами, происходят от того, что слабой модели дают слишком много свободы слишком рано.

Guided walkthrough1 of 5
  1. Установите Ollama (см. «Запуск моделей локально»), затем скачайте модель, помеченную для инструментов, например ollama pull llama3.1. Убедитесь, что она обслуживается по адресу http://localhost:11434 и что ollama list показывает её. Пока никакого агента — просто модель, которую вы можете вызвать.
Watch out
  • Локальный агент с инструментами всё равно может совершать реальные действия — изолируйте его в песочнице, требуйте подтверждения для разрушительных шагов и ограничивайте его циклы/бюджет.

Проверьте себя​

Проверьте себя

0/4
  1. Какова единственная самая важная причина, по которой команды строят агентов, работающих локально, а не против облачного API?
  2. Из каких четырёх частей состоит минимальная архитектура локального агента?
  3. Что означает, что LangGraph, CrewAI и OpenAI Agents SDK «не зависят от модели» для локального использования?
  4. Вы строите своего первого локального агента. Что нужно сделать ПЕРЕД добавлением любого инструмента, который пишет файлы или запускает команды?
Нажмите Enter или пробел, чтобы перевернуть карточку. Используйте стрелки влево и вправо для перехода между карточками.Показан термин.
1 / 6
Key takeaways
  • Локальный агент — это стандартный цикл использования инструментов, где облачная модель заменена моделью с открытыми весами на вашей машине — приватный, офлайн и бесплатный для итераций.
  • Минимальная архитектура = локальная модель, способная к инструментам + цикл вызова инструментов + инструменты + ограничитель/условие остановки. Сам цикл крошечный.
  • OpenAI-совместимая конечная точка Ollama (/v1) поддерживает вызов инструментов, так что любой фреймворк в формате OpenAI может управлять локальной моделью.
  • LangGraph, CrewAI и OpenAI Agents SDK не зависят от модели — направьте их на локальную конечную точку вместо облака.
  • Выберите модель, способную к инструментам, которая помещается в ваше оборудование, затем решайте с помощью небольшого eval вашей собственной задачи — а не лидерборда.
  • Будьте честны насчёт разрыва в возможностях и берите на себя безопасность: ограничивайте циклы и бюджет, изолируйте инструменты в песочнице и требуйте подтверждения для всего разрушительного.
  • Начинайте с простого: один чистый вызов инструмента → ограниченный цикл только для чтения → разрушительные инструменты с ограничителями → (опционально) фреймворк.

Источники и дополнительное чтение​