AI Platform Docs

Репозиторий ap-deploy содержит единственную поддерживаемую точку композиции полной среды Платформы ИИ. Он связывает исходные репозитории, окружения, общую инфраструктуру и зависимости действий.

Продуктовые репозитории agent-platform и langflow предоставляют код, образы и Helm charts, но намеренно не содержат собственных Garden Projects. Это исключает второй набор окружений, поставщиков Kubernetes и публичных адресов рядом с общим графом.

Основные понятия

Понятие	Назначение
`Project`	Описывает окружения, поставщиков инфраструктуры и общие переменные
`Environment`	Выбирает кластер, пространство имён, хранилище, адреса и реестр образов
`Build`	Собирает неизменяемый образ или другой артефакт
`Deploy`	Поддерживает длительно работающий Kubernetes-ресурс или Helm-релиз
`Run`	Выполняет конечную операцию, например согласование конфигурации идентификации
`Test`	Выполняет проверку с отдельной семантикой результата
`Dependency`	Задаёт обязательный порядок и передаёт результаты между действиями

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

Операции согласования внешнего состояния не полагаются только на вычисленную версию. Они выполняются идемпотентно и должны исправлять обнаруженное расхождение.

Граф среды

Эта схема раскрывает три этапа из упрощённого графа в руководстве разработчика. Действия внутри одного этапа не образуют обязательную последовательность: Garden выбирает и выполняет только зависимости запрошенного target.

Например, deploy.agent-platform напрямую зависит от трёх сборок образов, локальной шлюзовой топологии, согласования идентификации и сервиса эмбеддингов. Сборки и согласование идентификации являются параллельными зависимостями развёртывания, а не последовательными стадиями друг друга.

Ветки компонентов независимы настолько, насколько это допускают общие контракты. Техническая точка входа langflow не должна развёртывать исполняемые компоненты точки входа agent-platform, и наоборот.

Отдельное узкое исключение существует для артефакта lfx, который используется Low-code Runtime. Это зависимость сборки, а не зависимость двух работающих приложений.

Ещё одна явно отделённая зависимость target agent-platform в dev-local — OCI Registry data-only артефактов опубликованных агентов. Это не Registry application images: Garden продолжает собирать их через local-docker и загружать в Kind. Registry артефактов нужен Publisher во время работы платформы, поэтому Langflow и его build graph от него не зависят.

Пользовательские точки входа

Требуемый результат	Команда
Target `langflow`: Low-code IDE	`garden deploy langflow --env dev-local --yes`
Target `agent-platform`: другие компоненты платформы	`garden deploy agent-platform --env dev-local --yes`
Полная среда без тестовых данных	`garden deploy all --env dev-local --yes`
Общие тестовые пользователи	`garden run identity-fixtures --env dev-local --yes`
Тестовые данные для target `agent-platform`	`garden deploy agent-platform-fixtures --env dev-local --yes`
Тестовые данные для target `langflow`	`garden run langflow-fixtures --env dev-local --yes`
Полная тестовая среда	`garden deploy all-fixtures --env dev-local --yes`
Локальный доступ через шлюз	`garden run dev-local-edge-forward --env dev-local`
Восстановить Registry артефактов после запуска Kind	`garden run dev-local-artifact-registry --env dev-local --yes`
Проверить публикацию Runtime image по digest	`garden run dev-local-runtime-image --env dev-local --yes`

Сценарий all намеренно не включает тестовые данные. Обычное развёртывание не должно создавать тестовых пользователей и агентов.

Fixture actions активируются только при прямом выборе соответствующей точки входа или aggregate target all-fixtures. Вызов без имени garden deploy не создаёт тестовые данные.

Просмотр графа и плана

Посмотреть список действий и их зависимости:

garden get graph --env dev-local

Создать Mermaid-представление:

garden get graph --env dev-local --output json \
  | python3 scripts/garden_graph_to_mermaid.py --direction TB \
  > /tmp/ap-dev-local-garden.mmd

Посмотреть предполагаемые изменения без развёртывания:

garden deploy langflow --env dev-local --plan
garden deploy agent-platform --env dev-local --plan

План является вспомогательной проверкой. Он не заменяет развёртывание и проверку работающей среды.

Карта конфигурации

Путь в `ap-deploy`	Ответственность
`project.garden.yml`	Окружения, поставщики Kubernetes, пространство имён, реестр, хранилище, публичные адреса и закреплённые Git SHA
`actions/entrypoints.garden.yml`	Пользовательские aggregate targets `all` и `all-fixtures`
`actions/gateway.garden.yml`	Локальная шлюзовая инфраструктура и перенаправление портов
`actions/identity.garden.yml`	Keycloak, `realm`, секреты и согласование идентификации
`actions/agent-platform.garden.yml`	Сборки и развёртывание для target `agent-platform`
`actions/langflow.garden.yml`	Сборки и развёртывание для target `langflow`
`actions/preflight.garden.yml`	Проверки до изменения среды
`deploy/values/`	Наложения значений для конкретных окружений
`scripts/`	Связывание рабочих каталогов и статические проверки

Код компонентов, Dockerfile, Helm-чарты и принадлежащие приложению манифесты хранятся в репозитории владельца. Репозиторий композиции не должен содержать их копии.

Закреплённые версии и локальные ссылки

Общие среды используют полные Git SHA. Коммит ap-deploy тем самым фиксирует совместимый состав исходных версий.

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

python3 scripts/link_local_actions.py
garden get linked-repos --env dev-local

Garden читает текущие файлы рабочего каталога, включая незакоммиченные изменения. Исключение — immutable platform-lfx-wheel-image: он не линкуется на live checkout Langflow. Helper извлекает точно закреплённый коммит из локальной Git-базы в .garden/local-worktrees и линкует action на этот detached worktree. Скрипт не обновляет закреплённые SHA и не переносит Git-коммиты. Исходный Langflow commit в composition BOM всегда содержит закреплённый LFX commit в своей Git-истории, поэтому актуального develop достаточно для offline bootstrap.

Отключить локальные соответствия:

garden unlink action --all

Локальная ссылка не является синхронизацией кода с работающим контейнером. После изменения исходных файлов в текущей конфигурации нужно повторить развёртывание требуемой точки входа.

Правила изменения среды

Выбирайте минимальную требуемую пользовательскую точку входа.
Не используйте голый garden deploy, если достаточно одного target.
Не изменяйте управляемые ресурсы через ручной Helm или kubectl.
Не публикуйте разрешённую конфигурацию Garden, если она может содержать секретные значения.
Не используйте локальные соответствия исходного кода для ST.
Повторный запуск после частичной ошибки является нормальным способом восстановления идемпотентного графа.

Локальный Registry артефактов

Run action dev-local-artifact-registry поддерживает один pinned OCI Distribution container в Docker network Kind и настраивает containerd каждой ноды. Publisher использует push endpoint http://ap-dev-local-registry:5000/agent-platform/low-code, а Kubernetes Image Volume — canonical digest-only reference с prefix localhost:5001/agent-platform/low-code. Оба адреса указывают на одни repository и blobs.

Garden application image Low-code Runtime сначала существует только в local Docker store. Поэтому перед Agent Platform deploy отдельный action dev-local-runtime-image публикует exact build в repository agent-platform/runtime/low-code, читает подтверждённый Registry digest и передаёт Control Plane только ссылку localhost:5001/...@sha256:.... Mutable Garden tag не сохраняется в publication contract и не попадает в Kubernetes workload.

После остановки и повторного запуска Kind выполните:

garden run dev-local-artifact-registry --env dev-local --yes
curl -fsS http://127.0.0.1:5001/v2/

Чтобы отдельно проверить сборку, публикацию и digest output Runtime:

garden run dev-local-runtime-image --env dev-local --yes

Container и named volume принадлежат композиции dev-local, а не Helm chart приложения. Volume намеренно переживает удаление Kind. Удалять его можно только при подтверждённом полном reset после проверки, что Control Plane не содержит live или retained AgentVersion references. Обычный cleanup Garden и digest GC не удаляют всё хранилище.

Garden: граф и точки входа