--- theme: sii-course highlightTheme: github transition: slide transitionSpeed: default --- # Архитектура и расширение AI-продуктов **Как строить системы, которые растут без хаоса** **Лекция 8 • СИИ • ВолгГТУ САПРиПК • 2025** _От прототипа к production-ready архитектуре_ Note: Сегодня обсуждаем самую болезненную проблему AI-продуктов — как масштабироваться без complete rewrite. Вы научитесь проектировать модульные системы и документировать архитектурные решения. --- ## Почему AI-продукты "разваливаются" при росте?

### ❌ **Типичные проблемы** - "Быстро сделаем MVP" → monolithic mess - Hardcoded logic везде - Одна LLM цепочка для всех случаев - Нет fallback стратегий - **Добавить фичу = переписать всё**

### ✅ **Архитектурное мышление** - Модульность с первого дня - Четкие API boundaries - Pluggable components - Graceful degradation - **Расширение без breaking changes**

 💥 Reality check: 78% AI стартапов перезаписывают архитектуру при переходе от MVP к scale. Правильная архитектура с самого начала экономит месяцы работы 

Note: Большинство команд думают: "Сначала сделаем что-то работающее, потом refactor". В AI-продуктах это особенно болезненно из-за сложности LLM цепочек. --- ## C4 модель: как документировать AI архитектуру

### 🗺️ **C4 Model = Google Maps для кода** C4 — это иерархический подход к визуализации архитектуры от Simon Brown. Создает "карты кода" на разных уровнях детализации

📊 Level 1: Context

Кто: Business stakeholders
Что показывает: Система в окружении
AI пример: RAG система + пользователи + external APIs

🔧 Level 2: Container

Кто: Architects, DevOps
Что показывает: Deployable units
AI пример: Frontend, API Gateway, LLM Service, Vector DB

⚙️ Level 3: Component

Кто: Developers
Что показывает: Major classes/modules
AI пример: PromptManager, RAGRetriever, ResponseValidator

💻 Level 4: Code

Кто: Developers
Что показывает: Implementation details
AI пример: UML class diagrams, API schemas

Note: C4 решает проблему communication между разными ролями в команде. Business видит high-level context, разработчики — technical details. --- ## AI System Context Diagram (C4 Level 1) ```mermaid graph TB User[User
Product Manager] Admin[Admin
System Administrator] AISystem[AI Research Assistant
Helps users find and summarize research papers] ArXiv[ArXiv API
Research papers database] OpenAI[OpenAI API
Language model service] VectorDB[Vector Database
Embeddings storage] User --> AISystem Admin --> AISystem AISystem --> ArXiv AISystem --> OpenAI AISystem --> VectorDB style AISystem fill:#2563eb,color:#fff,stroke-width:3px style ArXiv fill:#f59e0b,color:#fff,stroke-width:2px style OpenAI fill:#8b5cf6,color:#fff,stroke-width:2px style VectorDB fill:#10b981,color:#fff,stroke-width:2px ``` **Level 1:** Показывает систему в контексте — кто использует, с чем интегрируется Note: Context diagram — первое что видят stakeholders. Должен быть понятен без технических знаний. --- ## Container Diagram (C4 Level 2): AI System Architecture ```mermaid graph TB subgraph "AI Research Assistant System" Web[Web Application
React Frontend
Port: 3000] API[API Gateway
FastAPI
Port: 8000] LLM[LLM Service
Python/LangChain
Port: 8001] RAG[RAG Service
Vector Search
Port: 8002] Monitor[Monitoring
Langfuse
Port: 8080] end VectorDB[(Vector Database
Chroma/Pinecone)] Cache[(Redis Cache
Response caching)] User[User] --> Web Web --> API API --> LLM API --> RAG RAG --> VectorDB LLM --> Cache API --> Monitor style Web fill:#f59e0b,color:#fff,stroke-width:2px style API fill:#2563eb,color:#fff,stroke-width:2px style LLM fill:#8b5cf6,color:#fff,stroke-width:2px style RAG fill:#10b981,color:#fff,stroke-width:2px ``` **Level 2:** Deployable units и их взаимодействие — что где развертывается Note: Container diagram показывает, как система deployed. Каждый container — отдельный процесс или deployment unit. --- ## Принципы модульной AI архитектуры

🧩 Separation of Concerns

Prompt Management: отдельный модуль
Model Inference: изолированный service
RAG Logic: независимый компонент
Response Validation: pluggable filters

🔌 Plugin Architecture

Model Providers: OpenAI, Anthropic, local
Vector Stores: Chroma, Pinecone, FAISS
Embedding Models: OpenAI, SentenceTransformers
Output Formats: JSON, markdown, structured

📡 API-First Design

RESTful interfaces между компонентами
OpenAPI specifications для всех endpoints
Async communication где возможно
Versioned APIs для backward compatibility

🛡️ Fault Tolerance

Circuit breakers для external services
Retry mechanisms с exponential backoff
Graceful degradation когда components fail
Health checks и monitoring

Note: Каждый принцип решает конкретную проблему scaling. Separation of Concerns позволяет independent development, Plugin Architecture — easy substitution. --- ## Fallback стратегии: как не "упасть" при сбоях

### 🛡️ **Принцип Graceful Degradation** **Better imperfect service than no service at all**

### ⚡ **LLM Fallback Chain** ```python class LLMService: def __init__(self): self.providers = [ GPT4Provider(), # Primary ClaudeProvider(), # Secondary GPT35Provider(), # Fallback LocalLLMProvider(), # Emergency StaticResponseProvider() # Last resort ] async def generate(self, prompt): for provider in self.providers: try: if provider.is_healthy(): return await provider.generate(prompt) except Exception as e: logger.warning(f"Provider {provider} failed: {e}") continue raise AllProvidersFailedException() ```

### 🔍 **RAG Fallback Scenarios** - **Vector DB down** → keyword search - **Embedding service failure** → cached embeddings - **No relevant documents** → general knowledge response - **Search timeout** → simplified query ### 📊 **Fallback Metrics** - Fallback activation rate - Quality degradation per fallback level - Recovery time to primary service

Note: Fallback — не просто error handling, а продуктовая стратегия. Пользователь должен получить хоть какой-то ответ, даже если не идеальный. --- ## Event-Driven Architecture для AI систем

### 📨 **Event Patterns в AI** ```python from dataclasses import dataclass from typing import Any import asyncio @dataclass class AIEvent: event_type: str user_id: str session_id: str data: Any timestamp: float class EventBus: def __init__(self): self.handlers = {} def subscribe(self, event_type: str, handler): if event_type not in self.handlers: self.handlers[event_type] = [] self.handlers[event_type].append(handler) async def publish(self, event: AIEvent): handlers = self.handlers.get(event.event_type, []) await asyncio.gather(*[h(event) for h in handlers]) # Usage bus = EventBus() bus.subscribe("user.query.received", log_user_query) bus.subscribe("llm.response.generated", update_metrics) bus.subscribe("rag.documents.retrieved", cache_results) ```

### 🔄 **Benefits для AI продуктов** - **Loose coupling** между AI компонентами - **Async processing** для expensive operations - **Easy A/B testing** через event routing - **Audit trail** для compliance ### 📊 **Event Types** - `user.query.received` - `prompt.expanded` - `documents.retrieved` - `llm.response.generated` - `response.validated` - `feedback.received`

 ⚡ Real benefit: Добавление новой фичи = новый event handler, старый код не трогается 

Note: Event-driven architecture особенно полезна для AI из-за множества async операций и потребности в A/B testing. --- # 🎯 Интерактив №1 ## Архитектурный рефакторинг **Задание (12 минут в группах):**

### 🏗️ **Для вашего проекта создайте:** 1. **C4 Context Diagram** — кто использует, с чем интегрируется 2. **Модульную декомпозицию** — какие компоненты можно выделить? 3. **Fallback стратегию** — что делать, если основной flow ломается? 4. **Plugin points** — где можно добавлять функциональность? ### 💡 **Обсудите:** - Что самое сложное для modularization? - Где potential bottlenecks?

**Результат: диаграмма + 3 архитектурных решения** Note: Фокус на practical decomposition существующих проектов. Студенты часто обнаруживают, что их monolithic код можно разбить проще, чем казалось. --- # ☕ Перерыв ## 10 минут _Время подумать о complexity вашей архитектуры_ --- ## SOLID принципы для AI компонентов

### 🏗️ **SOLID адаптированный для AI систем** Классические принципы OOP применимы к AI архитектуре с поправками на uncertainty и non-determinism

### 📝 **Single Responsibility** ```python # ❌ Плохо - всё в одном классе class AIAssistant: def process_query(self, query): # Expand query # Search documents # Generate response # Validate output # Log metrics pass # ✅ Хорошо - раздельные ответственности class QueryExpander: def expand(self, query): pass class DocumentRetriever: def search(self, query): pass class ResponseGenerator: def generate(self, query, context): pass ```

### 🔒 **Open/Closed Principle** ```python from abc import ABC, abstractmethod class LLMProvider(ABC): @abstractmethod async def generate(self, prompt: str) -> str: pass class OpenAIProvider(LLMProvider): async def generate(self, prompt: str) -> str: # OpenAI implementation pass class AnthropicProvider(LLMProvider): async def generate(self, prompt: str) -> str: # Anthropic implementation pass # Добавляем новых провайдеров без изменения existing кода ```

Note: SOLID принципы критичны для AI систем — они change frequently, нужна flexibility без breaking existing functionality. --- ## Architecture Decision Records (ADR)

### 📋 **ADR = Architectural Memory** ADR документируют архитектурные решения с контекстом, alternatives, и consequences. Это живая история решений команды

### 📄 **ADR Template** ```markdown # ADR-001: LLM Provider Selection ## Status Accepted ## Context Need reliable LLM service for production RAG system. Requirements: - Low latency (<2s p95) - High availability (99.9%) - Cost efficiency - Multi-modal capabilities ## Decision Use OpenAI GPT-4 as primary, Claude Sonnet as fallback ## Alternatives Considered - Only OpenAI: vendor lock-in risk - Only open-source: quality concerns - Multi-provider: complexity overhead ## Consequences + Reduced vendor risk + Better availability - Increased complexity - Higher implementation cost ```

### 🎯 **Why ADR matters** - **Team memory** — новые участники понимают решения - **Decision transparency** — видны trade-offs - **Change tracking** — можно пересмотреть outdated решения - **Compliance** — audit trail для enterprise ### 📊 **AI-specific ADRs** - Model selection criteria - Prompt versioning strategy - RAG architecture choices - Safety guardrails implementation

Note: ADR особенно важны для AI проектов — решения often non-obvious и требуют объяснения reasoning behind choices. --- ## Практический пример: расширение RAG системы

### 🚀 **Кейс: добавляем Multi-modal RAG** **Было:** Text-only RAG **Хотим:** Text + Images + Code search

### 🏗️ **Modular approach** ```python # Existing text retriever class TextRetriever: def search(self, query: str) -> List[Document]: pass # New retrievers без изменения существующего кода class ImageRetriever: def search(self, query: str) -> List[ImageDocument]: pass class CodeRetriever: def search(self, query: str) -> List[CodeDocument]: pass # Orchestrator объединяет все retrievers class MultiModalRetriever: def __init__(self): self.retrievers = [ TextRetriever(), ImageRetriever(), CodeRetriever() ] def search(self, query: str) -> List[Document]: results = [] for retriever in self.retrievers: results.extend(retriever.search(query)) return self.rerank(results) ```

### ⚡ **Deployment strategy** 1. **Phase 1:** Deploy новые retrievers в isolation 2. **Phase 2:** A/B test MultiModalRetriever 3. **Phase 3:** Gradual rollout с feature flags 4. **Phase 4:** Sunset old TextRetriever ### 📊 **Success metrics** - Search result relevance improvement - User engagement increase - No degradation in latency - Gradual feature adoption

Note: Правильная архитектура позволяет добавлять major features без disruption. Каждый новый retriever — independent module. --- ## Микросервисы vs Modular Monolith для AI

### 🏢 **Микросервисы: когда нужны** ```yaml # docker-compose.yml services: llm-service: image: llm-service:latest resources: limits: memory: 8G cpus: 4 rag-service: image: rag-service:latest resources: limits: memory: 4G cpus: 2 vector-db: image: chroma:latest volumes: - vector_data:/data ``` **Плюсы:** Independent scaling, technology diversity **Минусы:** Network latency, deployment complexity

### 🏗️ **Modular Monolith: когда лучше** ```python # Single deployable unit, но модульная структура app/ ├── llm/ # LLM module │ ├── providers/ │ └── __init__.py ├── rag/ # RAG module │ ├── retrievers/ │ └── __init__.py ├── api/ # API layer └── main.py # Single entry point ``` **Плюсы:** Simpler deployment, easier debugging **Минусы:** Shared resources, technology constraints

 🎯 AI-specific consideration: LLM calls often dominate latency, поэтому network overhead между services критичен. Start with modular monolith 

Note: Для AI систем рекомендую начинать с modular monolith — проще debug, deploy, и latency predictable. Микросервисы только когда scaling requirements forcing. --- # 🎯 Интерактив №2 ## Архитектурные паттерны в действии **Задание (10 минут):**

### 🔍 **Анализ real-world AI архитектур:** **Выберите один open-source AI проект:** - **LangChain** — framework для LLM приложений - **Haystack** — NLP framework с RAG - **Auto-GPT** — autonomous AI agents - **Chroma** — vector database ### 📊 **Найдите:** 1. **Архитектурные паттерны** — какие используются? 2. **Extension points** — как добавлять functionality? 3. **Mistakes** — что бы вы сделали по-другому?

**Результат: 3 lessons learned от каждой группы** Note: Real-world analysis помогает понять, как архитектурные принципы работают на практике. Студенты часто находят интересные patterns и anti-patterns. --- ## Эволюция архитектуры: от MVP к Enterprise

### 🚀 **Architectural Evolution Path** **MVP → Growth → Scale → Enterprise** _Каждая стадия требует different architectural decisions_

🥚 MVP Stage

Goal: Prove concept quickly
Architecture: Simple monolith
Focus: Functionality over scalability
Trade-offs: Technical debt acceptable

📈 Growth Stage

Goal: Handle increasing users
Architecture: Modular monolith
Focus: Performance optimization
Trade-offs: Start paying technical debt

⚡ Scale Stage

Goal: Massive throughput
Architecture: Distributed services
Focus: Horizontal scaling
Trade-offs: Complexity for performance

🏢 Enterprise Stage

Goal: Reliability & compliance
Architecture: Service mesh
Focus: Governance & security
Trade-offs: Stability over speed

Note: Нет "правильной" архитектуры — есть appropriate для текущей стадии. Преждевременная optimization kills productivity, а поздняя — kills product. --- ## Testing архитектуры: как проверить resilience

### 🧪 **Architecture Testing Patterns** ```python import pytest from unittest.mock import Mock class TestFallbackBehavior: def test_llm_fallback_chain(self): # Primary provider fails primary = Mock() primary.generate.side_effect = Exception("API down") # Secondary works secondary = Mock() secondary.generate.return_value = "fallback response" service = LLMService([primary, secondary]) result = service.generate("test prompt") assert result == "fallback response" assert primary.generate.called assert secondary.generate.called def test_graceful_degradation(self): # RAG retrieval fails, но system продолжает работать rag_service = Mock() rag_service.search.side_effect = TimeoutError() assistant = AIAssistant(rag_service) response = assistant.answer_question("What is AI?") # Should fall back to general knowledge assert response is not None assert "general knowledge" in response.metadata.source ```

### 🔥 **Chaos Engineering для AI** ```python # Simulate real-world failures def chaos_test_llm_resilience(): scenarios = [ lambda: simulate_api_timeout(), lambda: simulate_rate_limiting(), lambda: simulate_model_degradation(), lambda: simulate_network_partition() ] for scenario in scenarios: with scenario(): response = ai_system.process_query("test") assert response is not None assert response.confidence > 0.5 ``` ### 📊 **Testing Metrics** - Fallback activation rate under load - Response time degradation patterns - Quality maintenance during failures

Note: Architecture testing — не optional. AI системы особенно unpredictable, нужно proactively тестировать failure scenarios. --- ## Роли команды в архитектурных решениях

🧠 AI Engineer

Дизайн LLM и RAG компонентов
Определение AI-specific interfaces
Prompt management architecture
Model evaluation и A/B testing setup

⚙️ MLOps Engineer

Deployment и scaling strategies
Monitoring и observability setup
Infrastructure as Code
CI/CD pipeline design

💻 Fullstack Developer

API design и frontend integration
User experience optimization
Caching strategies
Performance profiling

🏗️ System Architect

Overall system design
Technology selection
Security architecture
ADR documentation и governance

 🤝 Collaborative principle: Архитектурные решения — result команды, но architect координирует и документирует 

Note: Хорошая архитектура — collaborative effort. Каждая роль приносит unique perspective, architect synthesizes в coherent design. --- ## Домашнее задание

### 📋 **Архитектурный рефакторинг проекта:**

**C4 диаграммы** вашего проекта (Context + Container levels)
**Модульная декомпозиция** — выделить минимум 3 independent компонента
**ADR документ** по ключевому архитектурному решению
**Fallback strategy** — что делать при failure основных компонентов
**Extension plan** — как добавить новую фичу без breaking changes

**Формат:** Диаграммы + ADR + план рефакторинга (2-3 страницы)

**Критерий успеха:** Другая команда может понять вашу архитектуру по документации Note: Homework должно result в actionable architectural plan. Не theoretical exercise, а практический blueprint для improvement существующих проектов. --- ## Ключевые выводы

### 🏗️ **Architectural Mindset** - **Modular from day one** — легче refactor модули, чем monolith - **Document decisions** — ADR как architectural memory - **Plan for failure** — fallback strategies не optional - **Evolution over revolution** — incremental architectural improvements

### ⚡ **AI-Specific Lessons** - **LLM uncertainty** требует robust fallback chains - **Event-driven patterns** handle async AI operations well - **Plugin architecture** enables model provider switching - **C4 documentation** essential для complex AI systems

### 🎯 **Team Success Factors** - Каждая роль участвует в архитектурных решениях - **Collaborative design** с clear ownership - **Living documentation** that evolves with system - **Testing resilience** как first-class concern

Note: Хорошая архитектура — это insurance policy. Инвестиция времени в начале saves months of painful refactoring later. --- ## Q&A и обсуждение

### 🤔 **Рефлексия** - Где в ваших проектах biggest architectural debt? - Какие решения принимались "на бегу" и требуют переосмысления? - Что самое сложное в модularization AI систем?

### 📚 **Следующая тема** **Лекция 9:** Демонстрация продукта - Effective demo strategies - Stakeholder communication - Technical storytelling

Note: Следующая лекция — про то, как представить вашу well-architected систему stakeholders и получить buy-in. --- ## Источники и ресурсы

### 📚 **Architecture Fundamentals** - **C4 Model** — c4model.com (Simon Brown) - **Architecture Decision Records** — adr.github.io - **SOLID Principles** — Robert C. Martin - **Building Evolutionary Architectures** — O'Reilly

### 🛠️ **AI Architecture Examples** - **LangChain Architecture** — github.com/langchain-ai/langchain - **Haystack Framework** — github.com/deepset-ai/haystack - **FastAPI Patterns** — fastapi.tiangolo.com/advanced/ - **Event-Driven Architecture** — martinfowler.com

### 🔧 **Tools & Frameworks** - **Structurizr** — C4 diagram tool - **Mermaid** — diagram as code - **PlantUML** — architecture diagrams - **draw.io** — collaborative diagramming

### 📖 **Дополнительное чтение** - **"Software Architecture for Developers"** — Simon Brown - **"Clean Architecture"** — Robert C. Martin - **"Microservices Patterns"** — Chris Richardson - **AI Engineering practices** — Chip Huyen

Note: Ресурсы покрывают как general architecture principles, так и AI-specific patterns. Рекомендую начать с C4 model для documentation. --- # Архитектура = фундамент успеха! **Следующая лекция:** Демонстрация продукта _От хаоса к управляемой системе роста_