ai-agents-for-beginners

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

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

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

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

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

Введение

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

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

После этого урока вы сможете:

Необходимые знания

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

Вам также понадобится:

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

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

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

SLM уступают в:

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

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

Microsoft Foundry Local

Microsoft Foundry Local — это лёгкая среда выполнения, которая загружает, управляет и обслуживает модели полностью на вашем устройстве. Самая важная для нас функция — это открытие OpenAI-совместимого HTTP эндпоинта — потому OpenAI SDK и клиент OpenAI из Microsoft Agent Framework работают с ним, меняя только base_url. Всё, что вы узнали о создании агентов, переносится напрямую; меняется только местоположение сервера на 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-совместимый эндпоинт (обычно http://localhost:PORT/v1). Ноутбук использует foundry-local-sdk для автоматического обнаружения эндпоинта, так что порт вводить вручную не нужно.

Вызов функций 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-совместимый эндпоинт, так что код агента почти такой же, как в облачных уроках — меняется только клиент:

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 эндпоинт**. 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. Какое реалистичное минимальное количество RAM для запуска локального агента из этого урока и что дает больше RAM?

Ответ Около **8 ГБ** — реалистичный минимум; 16 ГБ и более — комфортно. Больше RAM позволяет запускать более крупные и мощные модели и держать больше контекста в памяти. 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.