Вернуться к курсуСкачать Markdown

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

Для кого: инженеры, которые хотят превращать живую телеметрию экосистемы в 3D-визуализацию — опрашивать REST API alien-monitor, моделировать его топологию как типизированный граф и переносить сцены оракулов в React Three Fiber. Язык лаб: COURSE_LANG=en|ru|es|fr|zh · строки UI в i18n/ · этот гайд на русском. English · Español · Français · 中文

Сверка с текущей экосистемой

Лабораторные используют /api/topology Alien Monitor. У отдельного Service Mesh API есть /health, /v1/stats, /v1/agents и /v1/activity. Для сравнения запросите статистику Mesh и посмотрите tasks_24h и mesh_hops_24h. Объём в USD относится к телеметрии Mesh за 24 часа. Граф Alien Monitor собирайте по схеме его собственного API.

Зачем этот курс

alien-monitor — это живая 3D-карта экосистемы AIMarket: Hub, его пиры федерации и созвездие оракулов, каждый из которых рисуется как анимированная сцена React Three Fiber. Курс учит слою данных за этой картой. Вы научитесь опрашивать REST API монитора (/api/health, /api/topology, /api/reputation/*), моделировать ответы как типизированные структуры Python, ранжировать узлы оценками PageRank/EigenTrust от LUMEN и, наконец, сопоставлять слаг каждого оракула с камерой, акцентным цветом и метаданными примитива, которые фронтенд R3F использует для отрисовки сцены.

Каждая лаба детерминирована и работает без сети: если живой alien-monitor не запущен на 127.0.0.1:9100, лаба сама поднимает встроенный мок-сервер с той же формой REST — весь курс проходится без сети и без ключей. Каждая лаба печатает блок Trace, чтобы поведение можно было проверить.

Содержание

  1. Выбор трека
  2. Установка (10 минут)
  3. M1 — Здоровье монитора и режимы
  4. M2 — Модель графа топологии
  5. M3 — Репутация федерации
  6. M4 — Оценки PageRank от LUMEN
  7. M5 — Сопоставление сцен оракулов с R3F (продвинутый)
  8. Подключение живого монитора
  9. Упражнения и сертификат
  10. Наблюдаемость: блок Trace
  11. Типичные проблемы

Выбор трека

Трек Модули Время Живой монитор Фронтенд
Базовый M1 → M2 → M3 → M4 ~1,5 ч Мок (авто) Нет — чистый Python
Продвинутый Базовый + M5 +30 мин Мок или живой Спеки R3F
Мост к живому После M4 или M5 +30 мин Реальный alien-monitor Опционально

Мок-сервер подстраховывает все треки, так что запущенный монитор для прохождения курса не нужен. После каждой лабы смотрите блок Trace.

Установка (10 минут)

Шаг 1 — Клон и установка

git clone https://github.com/alexar76/aimarket-courses.git
cd aimarket-courses/3d-data-viz-course
pip install -e ".[dev]"

[dev] — единственный нужный extra: лабы опрашивают HTTP через стандартную библиотеку Python, тяжёлых зависимостей нет. [dev] добавляет pytest.

Шаг 2 — Тесты

pytest -q

Ожидается: все тесты проходят (паритет i18n по en/ru/es/fr/zh, разбор графа, маппинг R3F, проверки упражнений).

Шаг 3 — Первая лаба

python labs/lab01_health_probe.py
python labs/run_exercises.py

Шаг 4 — Язык интерфейса лаб

export COURSE_LANG=ru   # или es, по умолчанию en
python labs/lab01_health_probe.py

Все заголовки модулей, концепции, подписи и подсказки берутся из i18n/{en,ru,es,fr,zh}.json.

Шаг 5 — Google Colab

  1. Откройте сайт курса → Открыть в Colab на любой лабе.
  2. Выполните setup-ячейку (clone + pip install -e ".[dev]").
  3. При необходимости задайте os.environ["COURSE_LANG"] = "ru".
  4. Запустите ячейку лабы — мок-сервер работает и внутри Colab.

M1 — Здоровье монитора и режимы

Концепция: опрос /api/health и понимание режимов TEST, REAL и UNIVERSE. Лаба: labs/lab01_health_probe.py · ~15 мин · наблюдаемость, SRE

Шаги

  1. Прочитайте docstring в начале файла лабы.
  2. python labs/lab01_health_probe.py
  3. Разберите вывод: доступен ли живой монитор; строка result: status=ok mode=test. mode — источник данных монитора: test (мок), real (живая экосистема), universe (федеративный мульти-hub вид). Если использован мок — будет соответствующая пометка.
  4. Просмотрите courselib/viz.py: probe_health, HealthStatus, monitor_reachable, resolve_monitor_url.

Что доказывает

Рабочий REST-опрос и паттерн resolve_monitor_url() (живой-или-мок), который переиспользует каждая следующая лаба.

Самопроверка

M2 — Модель графа топологии

Концепция: разбор узлов и связей из /api/topology в типизированные графовые структуры. Лаба: labs/lab02_topology_graph.py · ~20 мин · нужен M1 · визуализация графов, React Flow

Шаги

  1. python labs/lab02_topology_graph.py
  2. Разберите вывод: число узлов и связей, затем до шести узлов с id, group, 3D-position и status.
  3. Строка Adjacency list: N directed edges — TopologyGraph.adjacency() убирает дубли рёбер и петли, давая форму для force-directed рендера.
  4. Изучите courselib/viz.py: MonitorNode, MonitorLink, TopologyGraph, Vec3.from_dict. Classmethod-ы from_api аккуратно приводят сырой JSON к типизированным dataclass.

Что доказывает

Типизированный граф в памяти (nodes, links, adjacency(), node_ids(), oracle_slugs()), на котором строятся M4 и M5.

Самопроверка

M3 — Репутация федерации

Концепция: обогащение графа доверия данными /api/reputation/peers из Hub. Лаба: labs/lab03_reputation_peers.py · ~20 мин · нужен M2 · EigenTrust, федерация

Шаги

  1. python labs/lab03_reputation_peers.py
  2. Вывод: Federation peers: N (mode), затем по каждому пиру name, trust_score, url. Пир без оценки печатается как —.
  3. В courselib/viz.py изучите ReputationPeer и ReputationPeers. trust_score имеет тип float | None, поэтому визуализация должна обрабатывать отсутствие данных.

Что доказывает

Слой федерации графа: каким внешним Hub доверяет этот монитор и насколько — вход для кодирования цвета/размера узлов-пиров.

Самопроверка

M4 — Оценки PageRank от LUMEN

Концепция: вызов /api/reputation/lumen и привязка оценок к узлам графа. Лаба: labs/lab04_lumen_scores.py · ~20 мин · нужен M2 · оракулы репутации

Шаги

  1. python labs/lab04_lumen_scores.py
  2. Вывод: узлы по убыванию оценки, у каждого столбик █ и значение с 4 знаками, затем PageRank iterations: N.
  3. Если LUMEN недоступен, лаба печатает строку LUMEN error, а не падает — обратите внимание на проверку lumen.ok.
  4. В courselib/viz.py изучите LumenScores и by_id(): метод связывает ids со scores, чтобы присоединить значения PageRank к id узлов из M2.

Что доказывает

Отображение id узла → вес репутации. LUMEN — оракул степенной итерации EigenTrust/PageRank; эти веса задают размер узлов на живой 3D-карте.

Самопроверка

M5 — Сопоставление сцен оракулов с R3F (продвинутый)

Концепция: сопоставление слагов оракулов с камерой, акцентом и метаданными примитивов для сцен Three.js. Лаба: labs/lab05_r3f_scenes.py · ~30 мин · нужен M2 · React Three Fiber, WebGL

Шаги

  1. python labs/lab05_r3f_scenes.py
  2. Вывод: Oracle R3F scenes: N, затем по каждой сцене slug, тип (r3f или ambient), кортеж camera, цвет accent и усечённое описание primitive.
  3. В courselib/viz.py изучите ORACLE_SCENE_META, R3FSceneSpec.for_oracle и map_graph_to_r3f_scenes. Таблица метаданных зеркалит alien-monitor/frontend/src/oracleScenes/meta.ts, поэтому Python-спека и фронтенд остаются синхронными.
  4. Обратите внимание на TopologyGraph.oracle_slugs(): он снимает префикс oracle- или ловит group == "oracle", после чего каждый слаг находит свои камеру/акцент/примитив (с разумными значениями по умолчанию).

Что доказывает

Список объектов R3FSceneSpec — ровно те камера, акцент и примитив, которые нужны <Canvas> React Three Fiber для отрисовки оракула. Это замыкает путь от REST-телеметрии к 3D-сцене.

Самопроверка

Подключение живого монитора

По умолчанию лабы работают со встроенным моком. Чтобы опросить настоящий alien-monitor:

# направьте лабы на любой запущенный монитор (по умолчанию http://127.0.0.1:9100)
export ALIEN_MONITOR_URL=http://127.0.0.1:9100
python labs/lab01_health_probe.py

Когда монитор доступен, resolve_monitor_url() пропускает мок, и появляется Live alien-monitor reachable: True. Те же пять лаб начнут визуализировать реальную экосистему: режимы переключатся с test на real/universe, топология покажет живые узлы, а LUMEN вернёт живые оценки PageRank.

Упражнения и сертификат

После лаб запустите проверки:

python labs/run_exercises.py             # все пять проверок
python labs/run_exercises.py --module m4 # один модуль

Проверка каждого модуля (exercise_m1_health_ok … exercise_m5_r3f_mapping) утверждает свойство, которому учила лаба, — например, m1 проверяет status == "ok" и корректный режим, m4 — что len(scores) == len(ids).

Когда все проверки пройдены, выпустите сертификат:

python labs/run_exercises.py --certificate "Иван Петров" --lang ru   # или en / es

Команда пишет certificate.html (id сертификата выводится из имени и даты). Откройте в браузере и Печать → Сохранить как PDF. Пройдите все проверки модулей, чтобы открыть сертификат.

Наблюдаемость: блок Trace

После каждой лабы (~5 мин):

  1. Найдите строку trace (N events) в конце вывода.
  2. Лабы логируют структурированные события: M1 — health, M2 — по одному node на узел, M3 — peer, M4 — lumen_score, M5 — r3f_scene.
  3. Сопоставьте каждое событие со строкой stdout — трейс это «лог юнит-теста» лабы: что опросили и что получили.

Типичные проблемы

Проблема Решение
ModuleNotFoundError: courselib Запуск из корня репозитория; лабы добавляют родительскую папку в sys.path
Live alien-monitor reachable: False Норма без живого монитора — встроенный мок включается автоматически
Нужен живой монитор Запустите alien-monitor на 127.0.0.1:9100 или задайте ALIEN_MONITOR_URL
Ошибка LUMEN / пустые оценки Монитор не вернул данные LUMEN; лаба защищена lumen.ok и продолжает работу
Пустые строки RU/ES export COURSE_LANG=ru; ключи i18n/ru.json должны совпадать с en.json
Падение паритета i18n в pytest Добавьте недостающий ключ во все три файла en/ru/es.json
Старый код в Colab Перезапустите setup-ячейку; закрепите ветку main

Гайды в docs/ правятся вручную — сначала EN, затем зеркала RU/ES.