7dayrag

Продакшн-ориентированный RAG + AI-агент, представленный как FastAPI-сервис. Создан как эталонная реализация для 7-дневного SaaS AI-проекта — обоснованные Q&A по бизнес-данным с цитатами, защитой от отказов и агентом, использующим инструменты для вызова внутренних API.

См. ARCHITECTURE.md для обоснования дизайна и плана поставки по дням.

Быстрый старт (без API-ключей)

Приложение полностью работает офлайн в режиме заглушки (детерминированные псевдо-эмбеддинги + скриптованный LLM). Добавьте реальные ключи позже, чтобы переключиться на OpenAI/Anthropic с автоматическим фейловером.

# 1. Postgres + pgvector
docker compose up -d db

# 2. Python deps
pip install -r requirements.txt

# 3. Configure (or skip: defaults match compose)
copy .env.example .env

# 4. Create schema + load the sample knowledge base
python -m scripts.seed_sample_data

# 5. Serve
uvicorn app.main:app --port 8000 --reload

Попробуйте

# Grounded Q&A with citations
curl -X POST localhost:8000/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{"question": "What is the uptime SLA for Business plans?"}'

# Agent that calls tools (ticket lookup)
curl -X POST localhost:8000/api/v1/agent/run \
  -H "Content-Type: application/json" \
  -d '{"task": "Check ticket TICKET-1001 and summarize its status."}'

# Raw hybrid retrieval (debug/tuning)
curl -X POST localhost:8000/api/v1/documents/search \
  -H "Content-Type: application/json" \
  -d '{"query": "refund window annual plan", "top_n": 3}'

Интерактивная документация: http://localhost:8000/docs

API

Каждый ответ содержит x-request-id; ошибки структурированы как {error: {code, message}}.

Конфигурация

Всё через переменные окружения / .env (см. .env.example). Ключевые настройки:

• LLM_PROVIDER: openai | anthropic | stub | auto (auto проходит по PROVIDER_ORDER с повторами и бэкоффом для каждого провайдера и фейловером; заканчивается на stub, если ключи не заданы)

• OPENAI_BASE_URL: укажите любой OpenAI-совместимый endpoint (Ollama, vLLM, шлюзы)

• MIN_VECTOR_SCORE: минимальный порог косинусной близости лучшего результата, ниже которого API отказывает вместо угадывания

• TICKETS_API_BASE_URL / ACCOUNTS_API_BASE_URL: направьте инструменты агента на реальные внутренние API; пусто = встроенные песочные данные

• REDIS_URL, CACHE_ENABLED, CACHE_TTL_SECONDS, RATE_LIMIT_PER_MINUTE: кэширование + ограничение скорости; отсутствие Redis влияет только на производительность, но не на доступность

Redis (кэширование + ограничение скорости)

Обоснованные ответы кэшируются (по ключу вопроса + конфигурации), а /api/v1/* ограничивается по скорости на IP клиента с фиксированным окном 60 секунд. Ответы содержат x-ratelimit-remaining; превышение лимита возвращает структурированный 429. /readyz сообщает о состоянии Redis; API работает даже при недоступности Redis. Кэшируются только не-отказные ответы (отказы могут меняться при обновлении документов).

docker compose up -d redis   # or just: docker compose up -d  (brings up db+redis+api+n8n)

MCP-сервер

Предоставьте те же возможности Claude Desktop или любому MCP-клиенту:

python mcp_server.py        # stdio transport

Инструменты: search_knowledge_base, answer_question, run_agent, lookup_ticket, lookup_account. Фрагмент конфигурации Claude Desktop:

{
  "mcpServers": {
    "7dayrag": {
      "command": "python",
      "args": ["/absolute/path/to/7dayrag/mcp_server.py"]
    }
  }
}

Автоматизация рабочих процессов n8n

docker compose up -d n8n → откройте http://localhost:5678 → импортируйте из workflows/:

Рабочие процессы вызывают http://api:8000 (сеть compose). Если вы запускаете n8n вне Compose, измените базовый URL на http://localhost:8000.

Проверьте webhook триажа после активации:

curl -X POST localhost:5678/webhook/ticket-triage \
  -H "Content-Type: application/json" -d '{"ticket_id": "TICKET-1001"}'

Как работает обоснование

1. Вопрос эмбеддится (той же моделью, что и при загрузке) и проходит гибридный поиск: косинусный top-K в pgvector + полнотекстовый top-K в Postgres, объединённые с помощью Reciprocal Rank Fusion.

2. Если векторная оценка лучшего результата ниже MIN_VECTOR_SCORE → отказ (без вызова LLM).

3. В противном случае нумерованный контекст передаётся модели со строгими правилами: цитировать как [n], отвечать только по контексту, иначе отвечать NOT_ENOUGH_CONTEXT.

4. Цитаты в ответе сопоставляются с исходными документами и возвращаются.

Тесты

docker compose up -d db      # integration tests need Postgres on :5433
pytest tests -q              # unit + integration; integration skips cleanly without DB
ruff check app tests scripts

21 тест: инварианты чанкинга, RRF-слияние, детерминизм эмбеддингов, поведение заглушки-провайдера, парсинг цикла агента, а также сквозные API-тесты против реальных Postgres/pgvector.

Развёртывание (staging)

cp .env.example .env   # add OPENAI_API_KEY
docker compose up -d --build
curl localhost:8000/readyz
curl -X POST localhost:8000/api/v1/admin/seed

Для AWS: те же образы → ECS Fargate + RDS Postgres (включите расширение pgvector). Для DigitalOcean: droplet + управляемый Postgres. Секреты только через переменные окружения / менеджер секретов.

Структура проекта

app/
  api/        FastAPI routes (documents, query, agent, health/admin)
  agent/      tool registry (KB search, ticket/account lookup) + bounded agent loop
  llm/        provider abstraction: openai, anthropic, stub + retry/failover router
  rag/        chunking, ingestion, hybrid retrieval (RRF), grounded generation
  cache.py    Redis: response cache + fixed-window rate limiting (fail-open)
  config.py   env-driven settings · db.py engine/session · db_init.py schema bootstrap
data/sample_docs/*.md    demo knowledge base
scripts/seed_sample_data.py
workflows/*.json         importable n8n automations (ticket triage, KB sync)
mcp_server.py            MCP tool server (stdio) for Claude Desktop / MCP clients
tests/

Следующие шаги (бэклог после проекта)

Стриминг (SSE), сбор обратной связи в eval-набор, этап реранкера, многотенантная RLS, плановое переиндексирование, версионирование промптов/A-B, дашборды стоимости.