Embedchain RAG-агенты: пошаговое руководство по созданию retrieval-агентов
🔗

Embedchain RAG-агенты: retrieval из коробки

Embedchain — фреймворк, превращающий любые данные в retrieval-агента за минуты. Поддерживает PDF, веб-страницы, YouTube, GitHub и десятки источников с автоматической индексацией и семантическим поиском.

intermediate ⏱ 15 мин
Data Sources PDF Web YouTube GitHub Embedchain Pipeline Chunker Embedder Vector DB Retriever LLM Response GPT-4o / Claude Ollama (local) User Query → Retrieve → Augment → Generate Embedchain RAG Architecture — Data → Embed → Retrieve → LLM

# 1. Что такое Embedchain и зачем он нужен

Embedchain — это open-source фреймворк для построения RAG-приложений (Retrieval-Augmented Generation) на Python. Его ключевое преимущество: вы указываете источники данных, а всё остальное — чанкинг, эмбеддинг, индексация, поиск — делает фреймворк автоматически. Поддерживает более 20 типов источников: PDF, DOCX, CSV, веб-страницы, YouTube-видео (через транскрипцию), GitHub-репозитории, базы знаний Notion, Slack-каналы и Sitemap-ы.

Под капотом Embedchain использует LangChain для оркестрации, но скрывает всю сложность за простым API. Вы выбираете LLM (OpenAI, Anthropic, Ollama, Groq), embedding-модель и векторную БД (Chroma, Qdrant, Weaviate, Pinecone), а фреймворк настраивает пайплайн. Идеально для быстрого прототипирования AI-агентов с retrieval-возможностями.

# Установка Embedchain с поддержкой всех провайдеров
pip install embedchain[all]

# Минимальный пример — добавляем веб-страницу и задаём вопрос
from embedchain import App

app = App.from_config(config_path="config.yaml")
app.add("https://docs.python.org/3/tutorial/")
answer = app.query("Как работают list comprehensions в Python?")
print(answer)

# 2. Конфигурация: LLM, embedding-модель и векторная БД

Embedchain конфигурируется через YAML-файл или Python-код. Вы можете выбрать OpenAI GPT-4o как LLM, text-embedding-3-small для эмбеддингов и Qdrant как векторную БД. Фреймворк поддерживает гибридный поиск (семантический + keyword), что повышает точность retrieval на смешанных данных.

Для продакшена настройте chunk_size и chunk_overlap. Слишком большие чанки размывают релевантность, слишком маленькие — теряют контекст. Оптимальный размер: 1000 токенов с перекрытием 200 для технической документации, 500 токенов с перекрытием 100 для FAQ и диалогов.

# config.yaml — продакшен-конфигурация Embedchain
llm:
  provider: openai
  config:
    model: "gpt-4o"
    temperature: 0.1
    max_tokens: 2000
    top_p: 0.95

embedder:
  provider: openai
  config:
    model: "text-embedding-3-small"
    dimensions: 1536

vectordb:
  provider: qdrant
  config:
    collection_name: "docs_knowledge"
    dir: "/data/qdrant"
    hnsw_config:
      m: 16
      ef_construct: 200

chunker:
  chunk_size: 1000
  chunk_overlap: 200
  length_function: len

# 3. Загрузка данных из разных источников

Embedchain умеет загружать данные из десятков источников единообразным методом add(). Можно скормить PDF с документацией продукта, веб-страницы конкурентов, YouTube-туториалы, CSV с данными поддержки — и всё это будет проиндексировано в одну векторную БД. Для YouTube используется transcripts API, для GitHub — клонирование и парсинг .md и .py файлов.

Важный прод-совет: используйте add() с параметром data_type, чтобы явно указать тип источника. Это ускоряет загрузку и исключает неверное определение типа. Для больших объёмов данных используйте add_batch() — он загружает параллельно, используя все ядра CPU.

import os
from embedchain import App

os.environ["OPENAI_API_KEY"] = "sk-..."
app = App.from_config("config.yaml")

# Добавляем данные из разных источников
app.add("docs/api-reference.pdf", data_type="pdf_file")
app.add("https://docs.example.com/architecture", data_type="web_page")
app.add("https://youtube.com/watch?v=abc123", data_type="youtube_video")
app.add("support_tickets.csv", data_type="csv")

# Пакетная загрузка директории с документами
app.add("/data/product-docs/", data_type="docs")

# Проверяем количество проиндексированных чанков
print(f"Chunks indexed: {app.db.count()}")

# 4. Кастомный RAG-пайплайн с переранжированием

Базовый retrieval возвращает топ-K чанков по косинусному сходству. Но для production-качества нужно переранжирование (reranking). Embedchain поддерживает Cohere Rerank и кастомные реранкеры. Переранжирование берёт top-20 чанков из векторного поиска и пересортировывает их с помощью кросс-энкодера, повышая релевантность первых 3-5 результатов на 30-40%.

Для сложных запросов настройте гибридный поиск: комбинацию семантического поиска (dense vectors) и BM25 (sparse/keyword). Это критично для запросов с техническими терминами, кодами продуктов и номерами, которые embedding-модели могут не уловить.

# Кастомный RAG-агент с переранжированием
from embedchain import App
from embedchain.config import BaseLlmConfig

class RerankAgent:
    def __init__(self):
        self.app = App.from_config("config.yaml")

    def smart_query(self, question: str, top_k: int = 10) -> str:
        # Получаем расширенный контекст
        contexts = self.app.search(question, num_documents=top_k)

        # Формируем промпт с контекстом и инструкцией
        prompt = f"""Ты — AI-ассистент технической поддержки.
        Используй ТОЛЬКО предоставленный контекст для ответа.
        Если информации недостаточно, скажи об этом честно.

        Контекст:
        {chr(10).join([f'- {c}' for c in contexts])}

        Вопрос: {question}
        Ответ:"""

        llm_config = BaseLlmConfig(
            temperature=0.0,
            max_tokens=1500,
            system_prompt="Отвечай на русском языке."
        )
        return self.app.llm.generate(prompt, llm_config)

agent = RerankAgent()
response = agent.smart_query(
    "Как настроить webhook-интеграцию с CRM?",
    top_k=10
)
print(response)

# 5. Embedchain как AI-агент с инструментами

Embedchain v0.2+ поддерживает режим агента с инструментами (tools). Вы можете дать агенту доступ к retrieval, веб-поиску, калькулятору и кастомным API. Агент сам решает, какой инструмент использовать для ответа на вопрос, применяя ReAct-паттерн (Reasoning + Acting).

Используйте режим агента когда пользовательские запросы требуют комбинации retrieval и действий: «Найди последние цены в документации, конвертируй в евро и сравни с рыночными». Агент достанет цены из векторной БД, вызовет API курса валют, сравнит и ответит.

# Режим агента с кастомным инструментом
from embedchain import App
from embedchain.loaders.web_page import WebPageLoader

app = App.from_config("config.yaml")

# Включаем режим агента
app.setup_agent(
    tools=["retrieve", "web_search"],
    agent_type="react",
    verbose=True
)

app.add("https://docs.stripe.com/api")
result = app.agent.query(
    "Найди pricing API Stripe в документации и сравни с актуальными ценами из интернета"
)
print(result)

# 6. Деплой и мониторинг Embedchain-агента

Для продакшена оберните Embedchain-агента в FastAPI-сервер. Добавьте фоновую переиндексацию по расписанию (например, через Celery beat), чтобы документы автоматически обновлялись. Используйте Redis для кеширования частых запросов — одинаковые вопросы будут отдаваться мгновенно.

Мониторьте метрики retrieval: precision@k (сколько релевантных чанков в топ-K), recall (доля найденных релевантных документов), и latency retrieval-пайплайна. Если precision падает ниже 0.7 — пересмотрите стратегию чанкинга или embedding-модель. Логируйте все запросы и ответы в PostgreSQL для аудита и улучшения промптов.

# FastAPI-сервер для Embedchain-агента
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from embedchain import App
import redis
import hashlib
import json

app = App.from_config("config.yaml")
api = FastAPI(title="Embedchain Agent API")
cache = redis.Redis(host="localhost", port=6379, db=0, decode_responses=True)

class QueryRequest(BaseModel):
    question: str
    session_id: str = "default"

class QueryResponse(BaseModel):
    answer: str
    sources: list[str]
    cached: bool

@api.post("/query", response_model=QueryResponse)
def query(req: QueryRequest):
    cache_key = hashlib.sha256(req.question.encode()).hexdigest()
    cached = cache.get(cache_key)

    if cached:
        data = json.loads(cached)
        return QueryResponse(
            answer=data["answer"],
            sources=data["sources"],
            cached=True
        )

    answer, sources = app.query(req.question, citations=True)
    cache.setex(cache_key, 3600, json.dumps({
        "answer": answer, "sources": sources
    }))
    return QueryResponse(answer=answer, sources=sources, cached=False)

# Запуск: uvicorn server:api --host 0.0.0.0 --port 8080

📊 Итог: Embedchain для RAG-агентов

Embedchain сокращает путь от идеи до рабочего RAG-агента с недель до часов. Ключевая сила — унифицированный API для загрузки любых данных и автоматическая настройка пайплайна. Для продакшена доработайте: переранжирование, гибридный поиск, кеширование ответов и фоновую переиндексацию. Для сложных сценариев включайте режим агента с ReAct-инструментами. Embedchain отлично интегрируется с LangSmith для трейсинга и LangFuse для observability. Начните с app.add() вашей документации — и через 5 минут у вас будет работающий retrieval-агент.