Skip to main content
Glama
deenesjakoruzh
HamdanProfessional

7dayrag

by HamdanProfessional
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

7dayrag

面向生产的 RAG + AI 智能体工作流，以 FastAPI 服务形式对外提供。作为 7 天 SaaS AI 项目的参考实现构建——基于业务数据、带引用的有依据问答，拒绝护栏，以及一个调用内部 API 的使用工具的智能体。

设计原理和逐日交付计划请参阅 ARCHITECTURE.md。

快速开始（无需任何 API 密钥）

应用在 stub 模式下可完全离线运行（确定性伪嵌入 + 脚本化 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: MCP Customer Support AI

试用

# 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

Method

Path

Purpose

GET

/healthz, /readyz

存活检查；就绪检查（数据库 + 提供商）

POST

/api/v1/documents

upsert 文档 → 分块 → 嵌入 → 索引

POST

/api/v1/documents/search

带融合分数的混合检索

POST

/api/v1/query

有依据的问答 {question} → 答案 + 引用

POST

/api/v1/agent/run

有界工具调用智能体，审计到 agent_runs

POST

/api/v1/admin/seed

重新加载示例知识库

每个响应都带有 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

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 融合、嵌入确定性、stub 提供商行为、智能体循环解析，以及针对真实 Postgres/pgvector 的端到端 API 往返测试。

部署（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）、将反馈捕获到评估集、重排序阶段、多租户 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

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers