Skip to main content
Glama
deenesjakoruzh
HamdanProfessional

7dayrag

by HamdanProfessional
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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

Related MCP server: support-agent-mcp

사용해 보기

# 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

메서드

경로

용도

GET

/healthz, /readyz

활성 상태; 준비 상태(DB + 프로바이더)

POST

/api/v1/documents

문서 업서트 → 청크 → 임베딩 → 인덱싱

POST

/api/v1/documents/search

융합 점수를 사용한 하이브리드 검색

POST

/api/v1/query

근거 기반 Q&A {question} → 답변 + 인용

POST

/api/v1/agent/run

제한된 도구 호출 에이전트, agent_runs에 감사 기록

POST

/api/v1/admin/seed

샘플 KB 재로드

모든 응답에는 x-request-id가 포함됩니다. 오류는 구조화된 {error: {code, message}} 형식입니다.

구성

모든 설정은 환경 변수 / .env(.env.example 참조)를 통해 이루어집니다. 주요 설정:

  • LLM_PROVIDER: openai | anthropic | stub | auto (auto는 PROVIDER_ORDER를 따라 프로바이더별 재시도 + 백오프 및 장애 조치를 수행하며, 키가 없으면 stub으로 종료)

  • OPENAI_BASE_URL: 모든 OpenAI 호환 엔드포인트(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 상태를 보고하며, Redis가 다운되면 API는 실패 개방(fail open) 방식으로 동작합니다. 거절 답변만 캐시되지 않습니다(거절은 문서 업데이트에 따라 변경될 수 있음).

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/에서 가져오기:

워크플로우

기능

ticket_triage.json

웹훅 POST /webhook/ticket-triage {ticket_id} → 입력 검증 → 7dayrag 에이전트 실행 → 트리아지 요약 반환(오류 분기 포함). 요약이 응답하는 위치에 Slack/이메일 노드를 교체하세요.

kb_sync.json

야간 일정 → /api/v1/admin/seed를 통해 지식 베이스 재동기화; CMS/Git/S3 소스를 /api/v1/documents에 연결하는 방식으로 교체 가능.

워크플로우는 http://api:8000(compose 네트워크)을 호출합니다. Compose 외부에서 n8n을 실행하는 경우 기본 URL을 http://localhost:8000으로 변경하세요.

활성화 후 트리아지 웹훅 테스트:

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

근거 기반(grounding) 작동 방식

  1. 질문이 임베딩되고(수집과 동일한 모델) 하이브리드 검색을 통해 실행됩니다: pgvector 코사인 top-K + Postgres 전문 검색 top-K, 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 융합, 임베딩 결정성, 스텁 프로바이더 동작, 에이전트 루프 파싱, 실제 Postgres/pgvector에 대한 엔드투엔드 API 왕복 테스트.

배포 (스테이징)

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: 드롭릿 + 관리형 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), 평가 세트로의 피드백 캡처, 리랭커 단계, 멀티테넌트 RLS, 예약 재인덱싱, 프롬프트 버전 관리/A-B 테스트, 비용 대시보드.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers