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はフェイルオープンします。拒否回答のみキャッシュされません（拒否はドキュメント更新に応じて変わるため）。

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

Webhook 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 に変更してください。

アクティベート後にトリアージWebhookをテスト：

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

グラウンディングの仕組み

  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