ru

Imported from microsoft/PhiCookBook (translations/ru/AGENTS.md). Install upstream with npx skills add microsoft/PhiCookBook --skill ru. Copyright stays with the author.

AGENTS.md

Обзор проекта

PhiCookBook — это всеобъемлющее репозиторий с рецептами, содержащий практические примеры, руководства и документацию по работе с семейством малых языковых моделей (SLM) Phi от Microsoft. Репозиторий демонстрирует различные варианты использования, включая вывод, дообучение, квантизацию, реализации RAG и мультимодальные приложения на разных платформах и фреймворках.

Основные технологии:

• Языки: Python, C#/.NET, JavaScript/Node.js
• Фреймворки: ONNX Runtime, PyTorch, Transformers, MLX, OpenVINO, Semantic Kernel
• Платформы: Microsoft Foundry, GitHub Models, Hugging Face, Ollama
• Типы моделей: Phi-3, Phi-3.5, Phi-4 (текстовые, визуальные, мультимодальные, варианты рассуждения)

Структура репозитория:

• /code/ — Рабочие примеры кода и образцы реализации
• /md/ — Подробная документация, руководства и инструкции
• /translations/ — Многоязычные переводы (50+ языков через автоматизированный рабочий процесс)
• /.devcontainer/ — Конфигурация контейнера разработчика (Python 3.12 с Ollama)

Настройка среды разработки

Использование GitHub Codespaces или Dev Containers (рекомендуется)

1. Открыть в GitHub Codespaces (самый быстрый вариант):

   • Нажмите на бейдж "Open in GitHub Codespaces" в README
   • Контейнер автоматически настроится с Python 3.12 и Ollama с Phi-3

2. Открыть в VS Code Dev Containers:

   • Используйте бейдж "Open in Dev Containers" в README
   • Контейнер требует минимум 16 ГБ оперативной памяти хоста

Локальная настройка

Требования:

• Python 3.12 или новее
• .NET 8.0 SDK (для примеров на C#)
• Node.js 18+ и npm (для примеров на JavaScript)
• Рекомендуется минимум 16 ГБ ОЗУ

Установка:

git clone https://github.com/microsoft/PhiCookBook.git
cd PhiCookBook

Для примеров на Python: Перейдите в конкретные директории с примерами и установите зависимости:

cd code/<example-directory>
pip install -r requirements.txt  # если файл requirements.txt существует

Для примеров на .NET:

cd md/04.HOL/dotnet/src
dotnet restore LabsPhi.sln
dotnet build LabsPhi.sln

Для примеров на JavaScript/Web:

cd code/08.RAG/rag_webgpu_chat
npm install
npm run dev  # Запустить сервер разработки
npm run build  # Собрать для производства

Организация репозитория

Примеры кода (/code/)

• 01.Introduce/ — Базовые введения и стартовые примеры
• 03.Finetuning/ и 04.Finetuning/ — Примеры дообучения разными методами
• 03.Inference/ — Примеры вывода на разном оборудовании (AIPC, MLX)
• 06.E2E/ — Примеры полноценных приложений
• 07.Lab/ — Лабораторные/экспериментальные реализации
• 08.RAG/ — Примеры Retrieval-Augmented Generation
• 09.UpdateSamples/ — Последние обновленные примеры

Документация (/md/)

• 01.Introduction/ — Вводные руководства, настройка окружения, платформенные инструкции
• 02.Application/ — Примеры приложений, организованные по типам (Текст, Код, Визуализация, Аудио и т.д.)
• 02.QuickStart/ — Руководства по быстрому старту для Microsoft Foundry и GitHub Models
• 03.FineTuning/ — Документация и туториалы по дообучению
• 04.HOL/ — Практические лабораторные работы (включая примеры на .NET)

Форматы файлов

• Jupyter Notebooks (.ipynb) — Интерактивные Python-руководства, помечены 📓 в README
• Python Scripts (.py) — Отдельные Python-примеры
• C# Projects (.csproj, .sln) — .NET приложения и примеры
• JavaScript (.js, package.json) — Веб и Node.js примеры
• Markdown (.md) — Документация и руководства

Работа с примерами

Запуск Jupyter ноутбуков

Большинство примеров предоставлены в виде Jupyter ноутбуков:

pip install jupyter notebook
jupyter notebook  # Открывает интерфейс браузера
# Перейдите к нужному файлу .ipynb

Запуск Python скриптов

cd code/<example-directory>
pip install -r requirements.txt
python <script-name>.py

Запуск .NET примеров

cd md/04.HOL/dotnet/src/<project-name>
dotnet run

Или соберите всё решение целиком:

cd md/04.HOL/dotnet/src
dotnet run --project <project-name>

Запуск JavaScript/Web примеров

cd code/08.RAG/rag_webgpu_chat
npm install
npm run dev  # Разработка с горячей перезагрузкой

Тестирование

Этот репозиторий содержит примеры кода и обучающие материалы, а не традиционный программный проект с юнит-тестами. Проверка работы обычно происходит следующим образом:

1. Запуск примеров — Каждый пример должен выполниться без ошибок
2. Проверка вывода — Убедитесь, что ответы моделей адекватны
3. Следование руководствам — Инструкции должны работать согласно документации

Типичный подход к проверке:

• Тест запуска примеров в целевой среде
• Проверка корректной установки зависимостей
• Проверка успешной загрузки/инициализации модели
• Подтверждение соответствия ожидаемого поведения документации

Стиль кода и соглашения

Общие рекомендации

• Примеры должны быть понятными, хорошо прокомментированными и обучающими
• Соблюдать языковые стандарты (PEP 8 для Python, стандарты C# для .NET)
• Примеры должны фокусироваться на демонстрации возможностей Phi моделей
• Включать комментарии, объясняющие ключевые концепции и параметры моделей

Стандарты документации

Форматирование URL:

• Используйте формат [text](../../url) без лишних пробелов
• Относительные ссылки: используйте ./ для текущей директории, ../ для родительской
• Не используйте локали стран в URL (избегайте /en-us/, /en/)

Изображения:

• Все изображения храните в директории /imgs/
• Используйте описательные имена на английском языке с буквами, цифрами и дефисами
• Пример: phi-3-architecture.png

Markdown файлы:

• Ссылайтесь на реальные рабочие примеры в директории /code/
• Поддерживайте документацию в актуальном состоянии с изменениями кода
• Используйте эмодзи 📓 для пометки Jupyter ноутбуков в README

Организация файлов

• Примеры кода в /code/ организованы по темам и функционалу
• Документация в /md/ отражает структуру кода, когда это возможно
• Держите связанные файлы (ноутбуки, скрипты, конфиги) вместе в поддиректориях

Руководство по Pull Request

Перед отправкой

1. Сделайте fork репозитория в свой аккаунт

2. Разделяйте PR по типам:

   • Исправления багов в отдельном PR
   • Обновления документации в другом
   • Новые примеры в отдельных PR
   • Исправления опечаток можно объединять

3. Разрешение конфликтов слияния:

   • Обновите локальную ветку main перед внесением изменений
   • Часто синхронизируйтесь с upstream

4. PR с переводами:

   • Должны включать переводы для ВСЕХ файлов в папке
   • Поддерживайте структуру, соответствующую оригиналу

Обязательные проверки

PR автоматически запускают GitHub workflow для валидации:

1. Проверка относительных путей — Все внутренние ссылки должны работать

   • Тестируйте ссылки локально: Ctrl+Click в VS Code
   • Используйте подсказки путей из VS Code (./ или ../)

2. Проверка локалей URL — Веб-адреса не должны содержать локали стран

   • Удалите /en-us/, /en/ и другие языковые коды
   • Используйте универсальные международные URL

3. Проверка битых ссылок — Все URL должны возвращать статус 200

   • Проверьте доступность перед отправкой
   • Учтите: некоторые ошибки могут быть связаны с сетевыми ограничениями

Формат заголовка PR

[component] Brief description

Примеры:

• [docs] Добавить руководство по выводу Phi-4
• [code] Исправить пример интеграции ONNX Runtime
• [translation] Добавить японский перевод вводных руководств

Общие паттерны разработки

Работа с моделями Phi

Загрузка моделей:

• Примеры используют разные фреймворки: Transformers, ONNX Runtime, MLX, OpenVINO
• Модели обычно скачиваются с Hugging Face, Azure или GitHub Models
• Проверьте совместимость моделей с вашим оборудованием (CPU, GPU, NPU)

Паттерны вывода:

• Генерация текста: большинство примеров использует чат/инструктивные варианты
• Визуализация: Phi-3-vision и Phi-4-multimodal для понимания изображений
• Аудио: Phi-4-multimodal поддерживает аудиовходы
• Рассуждение: Phi-4-reasoning варианты для сложных задач рассуждения

Платформо-зависимые заметки

Microsoft Foundry:

• Требует подписку Azure и API-ключи
• См. /md/02.QuickStart/AzureAIFoundry_QuickStart.md

GitHub Models:

• Бесплатный тариф для тестирования
• См. /md/02.QuickStart/GitHubModel_QuickStart.md

Локальный вывод:

• ONNX Runtime: кроссплатформенный, оптимизированный вывод
• Ollama: простое локальное управление моделями (преднастроено в контейнере разработки)
• Apple MLX: оптимизирован для Apple Silicon

Устранение неполадок

Частые проблемы

Проблемы с памятью:

• Модели Phi требуют много ОЗУ (особенно визуальные/мультимодальные варианты)
• Используйте квантизованные модели для ограниченных ресурсов
• См. /md/01.Introduction/04/QuantifyingPhi.md

Конфликты зависимостей:

• Примеры на Python могут требовать определенных версий библиотек
• Используйте виртуальные окружения для каждого примера
• Проверяйте индивидуальные файлы requirements.txt

Сбои загрузки моделей:

• Большие модели могут не загрузиться при медленном подключении
• Рассмотрите использование облачных сред (Codespaces, Azure)
• Проверяйте кэш Hugging Face: ~/.cache/huggingface/

Проблемы с .NET проектами:

• Убедитесь, что установлен .NET 8.0 SDK
• Используйте dotnet restore перед сборкой
• Некоторые проекты имеют настройки, специфичные для CUDA (Debug_Cuda)

Примеры JavaScript/Web:

• Используйте Node.js 18+ для совместимости
• Очистите node_modules и переустановите зависимости при проблемах
• Проверяйте консоль браузера на ошибки WebGPU

Получение помощи

• Discord: Присоединяйтесь к сообществу Microsoft Foundry в Discord
• GitHub Issues: Сообщайте об ошибках и проблемах в репозиторий
• GitHub Discussions: Задавайте вопросы и делитесь знаниями

Дополнительный контекст

Ответственный ИИ

Использование всех моделей Phi должно соответствовать принципам ответственного ИИ Microsoft:

• Справедливость, надежность, безопасность
• Конфиденциальность и защита данных
• Инклюзивность, прозрачность, подотчетность
• Используйте Azure AI Content Safety для промышленных приложений
• См. /md/01.Introduction/01/01.AISafety.md

Переводы

• Поддержка 50+ языков через автоматизированный GitHub Action
• Переводы находятся в директории /translations/
• Поддерживаются рабочим процессом co-op-translator
• Не редактируйте переведённые файлы вручную (автоматически сгенерированы)

Вклад в проект

• Следуйте инструкциям в CONTRIBUTING.md
• Согласуйте Contributor License Agreement (CLA)
• Соблюдайте Кодекс поведения Microsoft Open Source
• Не включайте в коммиты секреты и учетные данные

Многоязыковая поддержка

Это полиязычный репозиторий с примерами на:

• Python — ML/AI рабочие процессы, Jupyter ноутбуки, дообучение
• C#/.NET — Корпоративные приложения, интеграции ONNX Runtime
• JavaScript — Веб-ориентированный ИИ, вывод в браузере с WebGPU

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

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