225 lines
15 KiB
Markdown
225 lines
15 KiB
Markdown
# Alicorn — архитектурные решения
|
||
|
||
Сводка ключевых архитектурных решений (ADR-формат). Основано на спецификации в Outline (ветка «autonom agent alikorn»).
|
||
|
||
---
|
||
|
||
## 1. Разделение «Модель предлагает — Runtime располагает»
|
||
|
||
**Решение:** LLM (Ornith) только предлагает план в типизированном DSL. Runtime (Rust) детерминированно исполняет.
|
||
|
||
**Почему:**
|
||
- LLM на локальной модели даёт 20–150 t/s, слабый контекст, частые ошибки. Интерпретация плана внутри LLM = удвоение этих проблем.
|
||
- Detерминированный runtime даёт скорость (без интерпретации) и точность (повторяемость).
|
||
|
||
**Альтернативы:**
|
||
- LangChain/CrewAI/AutoGen — предполагают облачную LLM (дешёвый контекст, редкие ошибки). Не подходят под локальные модели.
|
||
- Чистый ReAct внутри LLM — «задыхается» через 5–10 шагов.
|
||
|
||
**Риски:** DSL-ограниченность (модель не может делать всё что угодно, только то, что умеет runtime). Компромисс ради детерминизма.
|
||
|
||
---
|
||
|
||
## 2. Append-only журнал (SQLite WAL) как источник правды
|
||
|
||
**Решение:** Все входы/выходы (llm.request/response, tool.call/result, anvil.check) пишутся в append-only журнал. Состояние = свёртка журнала.
|
||
|
||
**Почему:**
|
||
- Event Sourcing даёт replay «байт-в-байт».
|
||
- Журнал = аудит и отладка.
|
||
- Именно журнал, а не промежуточные рассуждения (экономия, приватность).
|
||
|
||
**Риски:** размер журнала; нужна ротация/компрессия. FULL sync для durability (влияет на latency).
|
||
|
||
---
|
||
|
||
## 3. Детерминизм и replay
|
||
|
||
**Решение:** Состояние = детерминированная свёртка журнала через reducer. Replay верифицируется в CI. Exactly-once через Transactional Outbox + Idempotency Key + Saga.
|
||
|
||
**Почему:** локальные models non-deterministic → без детерминированного executor'а нельзя гарантировать повторяемость.
|
||
|
||
**Альтернативы:**
|
||
- Хранение snapshot'ов состояния — дороже, сложно мержить.
|
||
- Pure functional state — сложно интегрировать с инструментами.
|
||
|
||
---
|
||
|
||
## 4. Pegas Memory: PostgreSQL + pgvector + Apache AGE
|
||
|
||
**Решение:** Единое хранилище — текст, векторы, граф, метаданные в Postgres.
|
||
|
||
**Почему:**
|
||
- pgvector = семантический поиск.
|
||
- AGE = граф связей (сущности, концепты).
|
||
- Один движок вместо трёх БД.
|
||
|
||
**Риски:** AGE (PostgreSQL extension для графов) — молодая технология, зрелость ниже, чем у Neo4j.
|
||
|
||
**Альтернативы:**
|
||
- Отдельный граф-сервер (Neo4j) — больше инфраструктуры.
|
||
- Qdrant + отдельная graph DB — сложнее поддержка.
|
||
|
||
---
|
||
|
||
## 5. Anvil: контроль прав и репутация (прозрачность правил)
|
||
|
||
**Решение:** Агент начинает с минимальными правами. Успешное действие → +репутация → расширение прав. Контракты: PermissionRegistry, ReputationOracle, BudgetController, CuriosityReward.
|
||
|
||
**Цель (главное):** **прозрачность правил** — агент видит, почему ему что-то можно/нельзя. Каждое решение «разрешено/запрещено» записано и объяснимо.
|
||
|
||
**Решение для MVP:** контроль = обычный код + **append-only журнал** (ADR-2). Журнал уже даёт аудируемость: можно пересчитать, какие права были у агента в любой момент и почему. Блокчейн НЕ нужен, пока нет переносимой репутации.
|
||
|
||
**Почему:**
|
||
- Безопасность: агент не может сразу получить все права.
|
||
- Прозрачность: решение «можно/нельзя» записано в журнал, объяснимо и аудируемо.
|
||
- Мотивация: curiosity как reward (внутренний драйв, не on-chain).
|
||
|
||
**Решение для v2 (эксперимент):** Solidity-контракты. Ценность появляется **только** если репутация/права агента должны быть переносимыми между машинами и верифицируемыми где-то ещё, а не только локально. Тогда блокчейн даёт доверие и переносимость.
|
||
|
||
**Риски:** стоимость транзакций; сложность интеграции с локальным runtime.
|
||
|
||
**Альтернативы:**
|
||
- Hardcoded权限-система — проще, но не масштабируема.
|
||
- Policy-based (OPA) — не такой «экономический».
|
||
- Solidity — только для v2, когда нужна переносимая репутация.
|
||
|
||
**Статус:** v1 = контроль через журнал + код; v2 = Solidity-эксперимент.
|
||
|
||
---
|
||
|
||
## 6. World Model (V-JEPA 2 / Agentic-JEPA)
|
||
|
||
**Решение:** Planner генерирует кандидатов → World Model предсказывает следующее состояние → агент выбирает с наивысшим сходством → верификация после выполнения.
|
||
|
||
**Почему:** локальные плохо планируют на много шагов вперёд. World Model даёт «представление о мире» без реального действия.
|
||
|
||
**Меры надёжности:**
|
||
- Планирование на один шаг (k=1).
|
||
- Калибровка доверия.
|
||
|
||
**Риски:** V-JEPA 2 — тяжёлая модель; локальный инференс может быть bottleneck.
|
||
|
||
**Альтернативы:**
|
||
- Chain-of-Thought — проще, но без «представления о мире».
|
||
- Реальные действия с откатом — дороже.
|
||
|
||
---
|
||
|
||
## 7. Pegas Core: Rust (dsh Harness)
|
||
|
||
**Решение:** Ядро на Rust. Роли: Planner (Ornith 1.5 A3B), Executor (Spark-X2.5-4B), Researcher (Nanbeige4.1-3B), Decision (Clef-Flash).
|
||
|
||
**Почему:**
|
||
- Rust = скорость + безопасность памяти + детерминизм.
|
||
- Разделение ролей = изоляция ошибок.
|
||
|
||
**Альтернативы:**
|
||
- Python (Hermes) — быстрее разработка, но медленнее и non-deterministic.
|
||
- Go — быстрее Python, но Rust лучше для системного кода.
|
||
|
||
---
|
||
|
||
## 8. Observability: OTEL + ClickHouse + Grafana
|
||
|
||
**Решение:** Трассировка, стоимость, качество через OpenTelemetry → ClickHouse → Grafana.
|
||
|
||
**Почему:**
|
||
- Наблюдаемость критична для автономного агента.
|
||
- ClickHouse = аналитика больших логов.
|
||
|
||
**Альтернативы:**
|
||
- Prometheus + Loki — сложнее агрегация.
|
||
- Локальные метрики — недостаточно для аудита.
|
||
|
||
---
|
||
|
||
## 9. MVP-стратегия
|
||
|
||
**Решение:** MVP = ReAct-цикл (Rust) + одна LLM (Ornith) + один MCP (Knowledge) + Postgres+pgvector (без AGE) + простой UI + heartbeat.
|
||
|
||
**Что НЕ в MVP:** мотивация/драйвы, Anvil, World Model, граф (AGE), мультиагентность, KTL, ClickHouse/Grafana, сложные метрики.
|
||
|
||
**План:** Нед 1 — ядро+LLM+журнал; Нед 2 — MCP+база знаний; Нед 3 — UI+heartbeat; Нед 4 — отладка+GitHub.
|
||
|
||
**Почему:** MVP должен доказать базовый цикл (задача → LLM → tool → ответ), а не всю архитектуру.
|
||
|
||
---
|
||
|
||
## 10. Связь с spark-mind (Animus)
|
||
|
||
**Решение:** spark-mind = первый слой Alicorn (чаты + память). Alicorn = полная архитектура.
|
||
|
||
**Почему:** spark-mind уже работает (персона, память, дашборд на :1337). Alicorn строится на этом фундаменте, но с детерминированным runtime'ом.
|
||
|
||
**Риски:** spark-mind non-deterministic (Python); Alicorn должен быть переписан на Rust.
|
||
|
||
---
|
||
|
||
## 11. Как читать документы Outline: обзор технологий, а не инструкция
|
||
|
||
**Решение:** Все документы Outline (ветка «autonom agent alikorn») — это **обзор существующих технологий и способов решения задач**, а не обязательная к исполнению спецификация.
|
||
|
||
**Мета-позиция:**
|
||
- Концепция — это **основная идея** (направление, философия), а не детальные требования.
|
||
- Каждый инструмент/технология/фреймворк — **гипотеза**, которую нужно **проверить на железе и реальных задачах**, а не принимать по описанию.
|
||
- «Существует проект X, который решает задачу Y» ≠ «мы берём X и всё работает». Реальная ценность — в измерении: как X ведёт себя на a2000 (1× RTX A2000 12 GB — боевой контур 24/7), на bge-m3, на локальных моделях с 8K контекстом.
|
||
|
||
**Почему:**
|
||
- Описания в репозиториях и статьях показывают лучший случай, а не поведение в твоей инфраструктуре.
|
||
- Выбор инструментов — эмпирический: gresmcp vs MinerU vs Segnatura, σ-RAG пороги, semantic_density — всё выводится на стенде, а не в спецификации.
|
||
- Контекст меняется: то, что актуально сегодня (версия, железо, модели), завтра устаревает. Идея устойчивее инструментов.
|
||
|
||
**Как применять:**
|
||
1. Прочитать как карту возможностей (« что вообще возможно»).
|
||
2. Выбрать кандидатов под MVP и реальные задачи.
|
||
3. Протестировать на железе: latency, качество, consumption GPU.
|
||
4. Отбросить то, что не показывает результат; оставить то, что работает.
|
||
|
||
**Пример:** BookRAG (Tree+KG+GT-Link) и RAGA (Read-Search-Verify-Construct) — проверены как близкие к твоей схеме. Kompyla/MetaKGEinrich/EvoMemKG — исследовать на v2, если MVP покажет потребность.
|
||
|
||
---
|
||
|
||
## 12. Модель встраиваний: тест EmbeddingGemma 2 вместо bge-m3
|
||
|
||
**Решение:** Рассмотреть EmbeddingGemma 2 (Google) как замену или дополнительную модель для эмбеддингов вместо bge-m3. Тестировать, не менять сразу.
|
||
|
||
**Железо (задаёт бюджет VRAM):**
|
||
- Боевой контур 24/7 — сервер **a2000: 1× RTX A2000 12 GB**. Эти 12 GB — общий бюджет на всё сразу: LLM-инференс агента, эмбеддинги, ASR и прочее.
|
||
- Вторая машина с **2× RTX 3080 Ti** — рабочая, для разработки: включается вручную и в 24/7-контуре не учитывается. Фоновые сервисы на неё ставить нельзя — они не переживут выключение.
|
||
|
||
**Почему:**
|
||
- bge-m3 (dim=1024, тяжёлая) занимает 12 GB на a2000 целиком; чтобы дать GPU LLM-инференсу агента, её приходится выключать.
|
||
- EmbeddingGemma 2 — лёгкая embed-модель (~200M). На фоне 24/7-фоновой эмбединговой нагрузки она не вытесняет LLM-инференс агента и не требует «выключить эмбеддер», чтобы освободить GPU.
|
||
- Для фоновой ингестсии (не интерактив) приоритет — низкое consumption GPU в фоне, а не максимальное качество поиска.
|
||
|
||
**Ключевое ограничение (обязательно учитывать):**
|
||
- Разный размер вектора = переиндексация. В контент-atom bge-m3 — единственная embed-модель (dim=1024); смена модели меняет размер вектора → переиндексация Qdrant + Postgres/pgvector.
|
||
- Значит замена — не «подкрутил конфиг», а пересборка эмбеддингов. Делать осознанно, лучше как отдельный запуск-эксперимент, а не в боевом контуре.
|
||
|
||
**Как проверять (на железе, не по описанию):**
|
||
- recall@k / MRR на реальных задачах против bge-m3.
|
||
- Latency эмбединга и consumption GPU параллельно с LLM-инференсом (не должно OOM'ить 12 GB на a2000).
|
||
- Если EmbeddingGemma 2 даёт приемлемый recall и не давит GPU — кандидат в MVP-стек. Иначе остаёмся на bge-m3.
|
||
|
||
**Статус:** к тестированию (гипотеза, не решение к внедрению).
|
||
|
||
---
|
||
|
||
## Статус решений
|
||
|
||
| # | Решение | Статус |
|
||
|---|---------|--------|
|
||
| 1 | Model proposes — Runtime disposes | Принято |
|
||
| 2 | Append-only журнал | Принято |
|
||
| 3 | Детерминизм + replay | Принято |
|
||
| 4 | PostgreSQL + pgvector + AGE | Принято (AGE — риск зрелости) |
|
||
| 5 | Anvil: контроль прав | v1 = журнал + код (прозрачность); v2 = Solidity (переносимая репутация) |
|
||
| 6 | World Model (V-JEPA 2) | Принято (для full-версии) |
|
||
| 7 | Rust-ядро | Принято |
|
||
| 8 | Observability (OTEL+ClickHouse) | Принято (для full-версии) |
|
||
| 9 | MVP-стратегия | Принято |
|
||
| 10 | Связь с spark-mind | Принято |
|
||
| 11 | Обзор технологий (не инструкция) | Принято |
|
||
| 12 | EmbeddingGemma 2 vs bge-m3 | К тестированию |
|