ai-agents-for-beginners

Создание локальных AI-агентов с использованием Microsoft Foundry Local и Qwen

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

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

Почему это может быть нужно? Три причины, которые часто возникают в реальной инженерной работе:

Но при этом вы меняете передовую облачную модель на малую языковую модель (SLM), которая работает на вашем CPU, GPU или NPU. Этот урок расскажет, как строить агентов, которые хороши в таких условиях, а не притворяться, что этих ограничений нет.

Введение

В этом уроке вы узнаете:

Цели обучения

После завершения урока вы будете знать, как:

Требования

Для этого урока предполагается, что вы завершили предыдущие уроки и уверенно работаете с:

Также вам потребуется:

Малые языковые модели: подходящий инструмент для локальной работы

Передовая облачная модель имеет сотни миллиардов параметров и за ней стоит дата-центр. Малые языковые модели имеют несколько миллиардов параметров и должны помещаться в RAM вашего ноутбука. Эта разница задаёт чёткие ожидания.

SLM хорошо справляются с:

SLM менее сильны в:

Выигрышная стратегия для локальных агентов: пусть SLM оркестрирует, а инструменты делают основную работу. Модель не должна знать ваш код — ей нужно знать, когда вызвать read_file и search_docs. Это идеально сочетается с сильными сторонами SLM.

flowchart LR
    U[Разработчик] --> A[Локальный агент SLM]
    A -->|выбирает инструмент| T1[read_file]
    A -->|выбирает инструмент| T2[search_docs RAG]
    A -->|выбирает инструмент| T3[analyze_code]
    T1 --> A
    T2 --> A
    T3 --> A
    A --> R[Ответ, полностью на устройстве]

Microsoft Foundry Local

Microsoft Foundry Local — лёгкая среда выполнения, которая скачивает, управляет и обслуживает модели полностью на вашей машине. Самая важная для нас функция — это предоставление OpenAI-совместимого HTTP endpoint — значит, OpenAI SDK и OpenAI клиент Microsoft Agent Framework работают с ней, меняя только base_url. Всё, что вы узнали о построении агентов, применяется напрямую; меняется только место endpoint — с облака на localhost.

Foundry Local также автоматически выбирает лучший билд модели под ваше оборудование — CPU, CUDA/GPU или NPU — так что не нужно оптимизировать вручную под каждую машину.

Установка

Установите Foundry Local (см. документацию для вашей ОС), затем проверьте, что всё работает:

# Установите (пример; следуйте документации для вашей платформы)
winget install Microsoft.FoundryLocal      # Windows
# brew install microsoft/foundrylocal/foundrylocal   # macOS

# Загрузите модель Qwen и запустите ее, затем запустите локальный сервис
foundry model run qwen2.5-7b-instruct
foundry service status

После запуска сервиса вы получите локальный OpenAI-совместимый endpoint (обычно http://localhost:PORT/v1). В ноутбуке используется foundry-local-sdk для автоматического обнаружения endpoint, так что не нужно жестко задавать порт.

Вызовы функций Qwen: почему это важно

Агент — только если он умеет вызывать инструменты. Многие SLM умеют чатиться, но генерируют ненадежные, некорректные вызовы. Qwen модели обучены именно для вызова функций и стабильно формируют корректные структуры вызовов — благодаря этому локальный чат-модель превращается в локального агента.

Поток такой же, как знакомый вам цикл вызова инструментов, только выполняется на устройстве:

sequenceDiagram
    participant U as Пользователь
    participant A as Агент Qwen (локально)
    participant T as Локальный инструмент
    U->>A: "Что делает auth.py?"
    A->>A: Решить: вызвать read_file
    A->>T: read_file("auth.py")
    T-->>A: содержимое файла
    A->>A: Анализ содержимого
    A-->>U: Объяснение

Локальный RAG

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

Мы используем Chroma — встроенное хранилище векторов, которое работает в процессе без необходимости отдельного сервера. Вся цепочка полностью локальна: локальная модель встраивания → локальные векторы → локальный поиск → локальная SLM.

flowchart TB
    D[Ваши документы / код] --> E[Локальная модель встраивания]
    E --> V[(Chroma векторная БД - на диске)]
    Q[Запрос агента] --> QE[Встроить запрос локально]
    QE --> V
    V -->|топ-k фрагментов| A[Агент Qwen]
    A --> Ans[Обоснованный ответ]

Это та же схема Agentic RAG из Урока 5 — единственное отличие, что все компоненты запускаются на вашей машине.

Локальные MCP-серверы

MCP — транспорт, а не облачный сервис. MCP сервер может работать как локальный процесс на stdio, предоставляя инструменты агенту через стандартный протокол. Это позволяет использовать растущую экосистему MCP-серверов — доступ к файловой системе, операции git, запросы к базам — полностью офлайн.

Безопасность отличается от облака, но не отсутствует: локальный MCP-сервер работает с правами вашего пользователя, так что ограничьте область его работы (например, каталог проекта, а не домашнюю папку) и проверяйте его выводы как входные данные.

Гибридные схемы облака и локали

Локальное первенство не значит только локальное. Зрелые системы маршрутизируют по чувствительности и сложности:

Ситуация Где выполняется
Чувствительный код/данные или офлайн Локальная SLM
Простейшая, ограниченная задача Локальная SLM (дешево, быстро)
Сложное многошаговое рассуждение на не чувствительных данных Облачная модель
Всё во время отключения связи Локальная SLM (грейсфул деградация)

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

flowchart LR
    Q[Запрос] --> S{Чувствительный или офлайн?}
    S -->|да| L[Локальный SLM]
    S -->|нет| C{Требуется глубокое рассуждение?}
    C -->|нет| L
    C -->|да| Cloud[Облачная модель]
    L --> Out[Ответ]
    Cloud --> Out

Практическое занятие: локальный инженерный ассистент

Откройте code_samples/17-local-agent-foundry-local.ipynb и пройдите задачу. Вы создадите локального инженерного ассистента, который полностью работает на вашей машине и может:

  1. Вызывать инструменты — через функцию вызова Qwen и Foundry Local.
  2. Выполнять локальные файловые операции — перечислять и читать файлы в каталоге проекта.
  3. Анализировать код — выводить базовые метрики по исходному файлу.
  4. Искать по документации — локальный RAG по папке с документацией с помощью Chroma.
  5. Использовать MCP — подключаться к локальному MCP-серверу (с мягким пропуском, если он не настроен).

Ни один запрос на инференцию в облаке не используется.

Пошаговое руководство

Ассистент подключается к Foundry Local через OpenAI-совместимый endpoint, так что код агента почти не отличается от уроков с облаком — меняется только клиент:

from foundry_local import FoundryLocalManager
from openai import OpenAI

# Foundry Local обнаруживает/загружает модель и предоставляет нам локальную конечную точку.
manager = FoundryLocalManager(\"qwen2.5-7b-instruct\")
client = OpenAI(base_url=manager.endpoint, api_key=manager.api_key)  # api_key — это локальный заполнитель

Инструменты — обычные функции на Python, ограниченные каталогом проекта:

def read_file(path: str) -> str:
    \"\"\"Read a file, but only inside the sandboxed project directory.\"\"\"
    full = (PROJECT_ROOT / path).resolve()
    if PROJECT_ROOT not in full.parents and full != PROJECT_ROOT:
        return \"Access denied: path is outside the project directory.\"
    return full.read_text(encoding=\"utf-8\")

Обратите внимание на проверку песочницы — даже локально инструмент, читающий произвольные пути, представляет риск. Ноутбук ограничивает каждый инструмент корнем одного проекта.

Проверка знаний

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

1. Назовите две конкретных причины запускать агента локально, а не в облаке.

Ответ Любые два из следующих: **конфиденциальность** (код и данные не покидают машину), **стоимость** (нет платы за токен при инференции) и **работа офлайн** (работает без сети — в самолёте, в защищённом объекте или при отключениях). Регуляторные/комплаенс-ограничения, запрещающие отправлять данные за пределы устройства, часто мотивируют конфиденциальность.

2. Какое рекомендуемое распределение обязанностей между SLM и инструментами в локальном агенте и почему?

Ответ Пусть SLM **оркестрирует** (решает, какой инструмент вызывать и с какими аргументами), а **инструменты выполняют основную работу** (читают файлы, извлекают документацию, вычисляют результаты). SLM хорошо подходит для ограниченных решений, таких как выбор инструмента, но слабее в широких знаниях и многошаговых рассуждениях, поэтому использование инструментов работает на их сильные стороны.

3. Что позволяет повторно использовать облачный код агента с Foundry Local?

Ответ Foundry Local предоставляет **OpenAI-совместимый HTTP endpoint**. OpenAI SDK и OpenAI клиент Agent Framework работают с ним, меняя только `base_url` (и используя локальный фиктивный API-ключ). В остальном код агента не меняется.

4. Почему мы используем именно функцию вызова модели Qwen, а не любую SLM?

Ответ Потому что агент должен формировать надёжные, корректные **вызовы инструментов**. Многие SLM умеют общаться, но генерируют некорректные или нестабильные структуры вызова. Модели Qwen обучены именно для вызова функций и стабильно создают вызовы инструментов, что превращает локальный чат в рабочего локального агента.

5. Какие компоненты локального конвейера RAG запускаются на машине?

Ответ Все: модель встраивания, векторная база данных (Chroma, на диске), этап извлечения и SLM. Документы встраиваются локально, хранятся локально, извлекаются локально и анализируются локальной моделью — ни один компонент не обращается к облаку.

6. Локальный MCP-сервер работает на вашей машине. Значит ли это, что он автоматически безопасен? Какие меры предосторожности следует соблюдать?

Ответ Нет. Локальный MCP-сервер работает с правами вашего пользователя, значит он имеет доступ ко всему, что доступны вам. Ограничьте его область (например, каталог одного проекта, а не всю домашнюю папку) и проверяйте его вывод как входные данные, прежде чем использовать.

7. Опишите разумное правило гибридного маршрутизации, включающее локальную модель.

Ответ Направляйте чувствительные или офлайн-запросы к локальной SLM; простые ограниченные задачи — к локальной SLM для скорости и экономии; сложное многошаговое рассуждение по не чувствительным данным — к облачной модели; и переходите на локальную SLM, если облако недоступно, чтобы агент деградировал плавно, а не падал. Это маршрутизация моделей (Урок 16) с локальной машиной в роли одной из моделей.

8. Какой реалистичный минимум ОЗУ для запуска локального агента из этого урока и что даёт больше памяти?

Ответ Около **8 ГБ** — реалистичный минимум; 16 ГБ и выше — комфортно. Больше памяти позволяет запускать большие и более мощные модели и держать больше контекста в памяти. GPU или NPU ускоряют инференцию, но не обязательны — Foundry Local выбирает CPU-билд при отсутствии ускорителя.

Задание

Расширьте локального инженерного ассистента до локального обозревателя документации для небольшого проекта на ваш выбор (можно использовать одну из папок уроков этого репозитория).

Ваша работа должна:

  1. Индексировать реальную папку с документацией/кодом в Chroma (не менее пяти файлов).

  2. Добавить инструмент find_todos, который сканирует проект на наличие комментариев TODO/FIXME и возвращает их с указанием файла и номера строки — с той же проверкой песочницы, что и у read_file.

  3. Задайте агенту три вопроса, которые заставят его комбинировать инструменты: один чисто RAG-вопрос, один, требующий прочтения конкретного файла, и один, требующий найти TODO.
  4. Замерьте время: засеките время на каждый из трёх ответов и запишите их в markdown-ячейке. Прокомментируйте, приемлема ли задержка для вашего предназначенного рабочего процесса.

Затем напишите короткий абзац о том, что бы вы перенесли в облако, а что оставили бы локально для этого рецензента, и почему. Оценивается, правильно ли связаны локальные компоненты и насколько логичен ваш гибридный подход — а не качество модели.

Итого

В этом уроке вы создали агента, который полностью работает на вашем собственном компьютере:

Это завершает цикл развертывания: Урок 16 масштабировал агентов в Microsoft Foundry, а этот урок масштабировал их вниз на одну рабочую станцию. Следующий урок посвящён безопасности развернутых агентов.

Дополнительные ресурсы

Предыдущий урок

Развёртывание масштабируемых агентов

Следующий урок

Обеспечение безопасности AI агентов

Отказ от ответственности: Этот документ был переведен с использованием сервиса машинного перевода Co-op Translator. Несмотря на наши усилия по обеспечению точности, имейте в виду, что автоматический перевод может содержать ошибки или неточности. Оригинальный документ на его исходном языке следует считать авторитетным источником. Для получения критически важной информации рекомендуется обратиться к профессиональному человеческому переводу. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникшие в результате использования этого перевода.

This site is open source. Improve this page.