使用说明

需求图API

A. 图增强检索增强生成 （GraphRAG）系统，带有聊天界面 Jama软件“需求管理和可追溯性基本指南” 知识库。特点和 代理RAG架构 基于LangGraph构建，具有自主工具选择、多跳推理和自我批评功能。包括4级图丰富管道、自动查询路由、具有渐进元数据的SSE流、会话持久性和具有综合评估的端到端LangSmith可观察性。

现场演示

	URL
聊天界面	graphrag.norfolkaibi.com
Swagger API文档	graphrag-api.norfolkaibi.com/docs

截图

GraphRAG explanatory response — intent badge, citations, entity concepts, media gallery

Text2Cypher structured response — generated Cypher query with tabular results

特性

图形丰富的RAG管道

每个查询都经过一个多阶段的丰富管道，该管道逐步从Neo4j知识图中添加上下文：

级别	丰富	它增加了什么
1	窗口扩展	相邻块文本通过 `NEXT_CHUNK` 叙事连续性关系
2	实体提取	实体 `MENTIONED_IN` 具有属性的块：名称、类型、定义、益处、影响
3	语义遍历	相关实体通过 `RELATED_TO`, `ADDRESSES`, `REQUIRES`, `COMPONENT_OF` 关系
4	域上下文	行业标准、图像、网络研讨会、视频、交叉引用和术语表定义

自动查询路由

两级分类器将每个查询路由到适当的处理程序：

第一阶段——关键词匹配：一组冻结的结构化触发器("list all", "how many", "count", "table of")加上用于即时分类的正则表达式模式
第二阶段——LLM分类：对于不明确的查询，LLM分类器（温度0）返回 {"intent": "structured" | "explanatory"}

意图	处理程序	输出
解释性	自主工具选择+图形丰富的代理RAG	带有引用、实体、媒体的流式散文
结构化的	Text2Cypher--自然语言转换为Cypher查询	生成的查询+表格结果

代理RAG架构

建立在 LangGraph，代理系统自主地协调检索和合成：

┌─────────────────────────────────────────────────────────────────┐
│                      AGENTIC ORCHESTRATOR                        │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐  │
│  │   RAG    │───▶│ Research │───▶│Synthesis │───▶│  Output  │  │
│  │ Subgraph │    │ Subgraph │    │ Subgraph │    │          │  │
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘  │
│       │               │               │                         │
│       ▼               ▼               ▼                         │
│  Query Expansion  Entity        Self-Critique                   │
│  Parallel Search  Exploration   Revision Loop                   │
└─────────────────────────────────────────────────────────────────┘

子图	节点	能力
检索增强生成	expand_query→ 并行重试→ dedupe_rank	带回溯推理的多查询扩展
研究	识别实体→ explore_instance（循环）	带条件迭代的深度实体探索
合成	草稿_答复→ 批评→ 修订→ 格式	自动修订的自我批评

主要特点：

7代理工具：graph_search、text2cypher、explore_instance、lookup_standard、search_definition、lookup_term、get_webinars
对话持久性：PostgresSaver用于线程隔离的多轮对话
自我批评：CRITIC提示评估答案的完整性，并在需要时触发修订
性能跟踪：子图执行时间和优化提示的内置指标
成本分析：LLM令牌跟踪，每个模型的成本估算

SSE流媒体聊天

通过渐进式元数据传递的服务器发送事件上的响应流：

Explanatory:  routing → sources → token (repeated) → done
Structured:   routing → cypher → results → done

每个事件都携带键入的JSON有效载荷(StreamEventType StrEnum有7个值： ROUTING, SOURCES, TOKEN, CYPHER, RESULTS, DONE, ERROR).前端通过自定义方式使用这些 useSSEChat 反应钩子。

附加功能

搜索模式 --向量相似性、混合（向量+全文，权重可调）和图形丰富的搜索端点
术语表和定义 --基于知识图的模糊匹配项查找
行业标准 --按行业（汽车、医疗、航空航天、国防、铁路）筛选的可查询标准
架构浏览器 --节点标签、关系和计数；每个实体关系图
用户反馈 --分数+类别+校正，与LangSmith跑步ID相关
分层评估 --通过GitHub Actions对发布标签（第3层）和夜间深度评估（第4层）进行自动基准测试

建筑

┌──────────────────────┐
│   React 19 + Vite    │
│   Tailwind CSS v4    │
│   (Vercel)           │
└──────────┬───────────┘
           │ SSE / REST
           ▼
┌──────────────────────────────────────┐
│   FastAPI + Agentic Orchestrator     │
│   (LangGraph StateGraph)             │
│   ├─ Query Router                    │──── LangSmith Tracing
│   ├─ Tool Selection                  │
│   └─ Self-Critique Loop              │
│   (Railway)                          │
└──────┬───────┬───────────────────────┘
       │       │              │
       ▼       ▼              ▼
  ┌─────────┐ ┌────────────┐ ┌──────────────┐
  │ Agentic │ │ Text2Cypher│ │  PostgreSQL  │
  │   RAG   │ │  (LLM →    │ │  Checkpoints │
  │Subgraphs│ │   Cypher)  │ │ (Persistence)│
  └────┬────┘ └──────┬─────┘ └──────────────┘
       │             │
       ▼             ▼
┌──────────────────────┐
│   Neo4j AuraDB       │
│   Knowledge Graph    │
│   (Chunks, Entities, │
│    Media, Standards) │
└──────────────────────┘

技术栈

层	技术	目的
前端	React 19、Vite 7、Tailwind CSS 4	带有SSE流媒体、实体徽章、媒体画廊的聊天UI
后端	FastAPI，Python 3.12+，uv	REST API，带SSE端点，异步I/O
图形数据库	Neo4j AuraDB、Neo4j graphrag	知识图存储、向量索引、Cypher查询
LLM	OpenAI GPT-4o，Voyage AI Voyage-4	答案生成、意图分类、嵌入
代理编排	LangGraph，LangGraph检查点postgres	有状态代理图，子图组合，会话持久性
链构成	朗链核心、朗链开放	RAG链建设、及时管理
可观察性	LangSmith	跟踪、反馈、即时版本控制、评估
CI/CD	GitHub操作，Codecov	Lint，测试，覆盖率，评估，提示同步
部署	铁路（后端），Vercel（前端）	Docker容器，边缘CDN

API终点

方法	路径	描述
`POST`	`/chat`	带有自动意图路由的SSE流式聊天
`GET`	`/chat/{thread_id}`	按线程ID检索对话状态
`POST`	`/chat/{thread_id}/continue`	继续现有的对话线程
`GET`	`/chat/routing-guide`	面向用户的查询路由文档
`POST`	`/search/vector`	语义向量相似度搜索
`POST`	`/search/hybrid`	向量+关键字搜索，权重可调
`POST`	`/search/graph`	多级图丰富搜索
`GET`	`/definitions/{term}`	查找特定的词汇表术语（模糊匹配）
`GET`	`/definitions`	列出或搜索所有术语表术语
`GET`	`/standards/{name}`	查找特定的行业标准
`GET`	`/standards`	使用可选行业筛选器列出或搜索标准
`GET`	`/schema`	节点标签、关系和计数
`GET`	`/schema/entity/{name}`	探索实体及其关系
`POST`	`/feedback`	提交响应反馈（评分、类别、更正）
`GET`	`/health`	使用Neo4j连接状态进行健康检查

知识图谱

节点类型

类别	标签	关键属性
内容	`Chunk`, `Article`, `Definition`	文本、文章标题、url、术语、定义
域实体	`Concept`, `Challenge`, `Bestpractice`, `Standard`, `Methodology`, `Artifact`, `Tool`, `Role`, `Processstage`, `Industry`	名称、显示名称、定义、好处、影响
媒体	`Image`, `Webinar`, `Video`	标题、URL、ALT文本、缩略图

关系

关系	方向	目的
`FROM_ARTICLE`	Chunk→ 文章	来源
`NEXT_CHUNK`	Chunk→ Chunk	顺序排序（窗口扩展）
`MENTIONED_IN`	实体→ 块	实体提取
`RELATED_TO`	实体→ 实体	跨域连接
`ADDRESSES`	实体→ 实体	挑战解决
`REQUIRES`	实体→ 实体	依赖关系
`COMPONENT_OF`	实体→ 实体	部分整体
`APPLIES_TO`	标准→ 行业	行业适用性
`HAS_IMAGE` / `HAS_WEBINAR` / `HAS_VIDEO`	文章→ 媒体	媒体丰富
`REFERENCES`	文章→ 文章	交叉引用

实体颜色编码

前端显示知识图实体的颜色编码徽章：

实体类型	颜色	示例
概念	灰色	需求可追溯性，商业智能
挑战	红色	范围蠕变，需求波动
最佳实践	绿色	变更管理，持续验证
Artifact	Blue	设计规范、测试用例
标准	紫色	ISO 13485，DO-178C

快速开始

Docker（推荐）

# Clone and configure
git clone https://github.com/arthurfantaci/requirements-graphrag-api.git
cd requirements-graphrag-api
cp .env.example .env
# Edit .env with your Neo4j, OpenAI, and LangSmith credentials

# Start both services
docker-compose up

# Backend API: http://localhost:8000
# Frontend:    http://localhost:5173
# API Docs:    http://localhost:8000/docs

没有Docker

# Backend
cd backend
uv sync --extra dev
uv run uvicorn requirements_graphrag_api.api:app --reload

# Frontend (new terminal)
cd frontend
npm install
npm run dev

部署

平台	服务	URL	配置
铁路	后端API	graphrag-api.norfolkaibi.com	`railway.toml`, `backend/Dockerfile`
Vercel	前端	graphrag.norfolkaibi.com	`frontend/vercel.json`
Neo4j AuraDB	图形数据库	--	`neo4j+s://` env变量中的URI

CI/CD和评估

工作流	触发器	它的作用
持续集成 (`ci.yml`)	推送到主/开发，PR	Ruff lint+格式检查，覆盖率pytest，Codecov上传
评估 (`evaluation.yml`)	发布标签、夜间时间表、手册	发布的第3级完整基准；每晚进行4级深度评估（失败时自动创建GitHub问题）
同步提示 (`sync-prompts.yml`)	推送到主（提示文件），手动	将版本化的提示推送到LangSmith Hub
部署 (`deploy.yml`)	手动调度	手动Vercel部署（禁用--Vercel GitHub集成处理自动部署）

环境变量

看 backend/.env.example 对于带有内联文档的完整模板。

变量	必填	默认	描述
`NEO4J_URI`	是	--	Neo4j连接URI(`neo4j+s://` 用于生产）
`NEO4J_USERNAME`	是	--	Neo4j用户名
`NEO4J_PASSWORD`	是	--	Neo4j密码
`NEO4J_DATABASE`	没有	`neo4j`	Neo4j数据库名称
`OPENAI_API_KEY`	是	-	OpenAI API密钥
`OPENAI_MODEL`	没有	`gpt-4o`	LLM生成和分类模型
`EMBEDDING_MODEL`	没有	`voyage-4`	嵌入模型（必须与Neo4j索引匹配）
`EMBEDDING_DIMENSIONS`	没有	`1024`	嵌入向量维度（必须与索引匹配）
`VOYAGE_API_KEY`	是	-	Voyage AI API键用于查询时嵌入
`OPENAI_EMBEDDING_MODEL`	没有	`text-embedding-3-small`	OpenAI嵌入模型（仅限离线RAGAS评估者）
`VECTOR_INDEX_NAME`	没有	`chunk_embeddings`	Neo4j矢量索引名称
`SIMILARITY_K`	没有	`6`	要检索的相似块的数量
`NEO4J_MAX_POOL_SIZE`	没有	`5`	连接池大小（无服务器时较小）
`NEO4J_CONNECTION_TIMEOUT`	没有	`30.0`	连接超时（秒）
`LANGSMITH_TRACING`	没有	`false`	启用LangSmith跟踪
`LANGSMITH_API_KEY`	否	-	LangSmith API密钥
`LANGSMITH_PROJECT`	没有	`graphrag-api-dev`	LangSmith项目名称
`CHECKPOINT_DATABASE_URL`	没有用于会话持久性的PostgreSQL URL（LangGraph检查点）
`CORS_ORIGINS`	没有	`localhost:3000,5173`	允许的CORS源（逗号分隔）
`VITE_API_URL`	是（前端）	-	前端的后端API URL

项目结构

requirements-graphrag-api/
├── .github/workflows/
│   ├── ci.yml                          # Lint + test + coverage
│   ├── evaluation.yml                  # Tiered evaluation (release + nightly)
│   ├── sync-prompts.yml                # LangSmith Hub prompt sync
│   └── deploy.yml                      # Manual Vercel deploy
│
├── backend/
│   ├── src/requirements_graphrag_api/
│   │   ├── api.py                      # FastAPI app with lifespan (driver init)
│   │   ├── config.py                   # AppConfig with env validation
│   │   ├── neo4j_client.py             # Driver creation helpers
│   │   ├── observability.py            # LangSmith tracing setup
│   │   ├── exceptions.py               # Custom exception hierarchy
│   │   ├── core/
│   │   │   ├── retrieval.py            # Vector/hybrid/graph search + 4-level enrichment
│   │   │   ├── generation.py           # RAG answer generation + SSE streaming
│   │   │   ├── routing.py              # Intent classification (keyword + LLM)
│   │   │   ├── text2cypher.py          # Natural language → Cypher translation
│   │   │   ├── definitions.py          # Glossary/definition lookup
│   │   │   ├── standards.py            # Industry standards queries
│   │   │   └── agentic/                # LangGraph agentic orchestration
│   │   │       ├── state.py            # TypedDict state definitions
│   │   │       ├── tools.py            # Agent tool definitions (7 tools)
│   │   │       ├── orchestrator.py     # Main composed graph with routing
│   │   │       ├── checkpoints.py      # PostgresSaver configuration
│   │   │       ├── streaming.py        # SSE streaming utilities
│   │   │       └── subgraphs/          # RAG, Research, Synthesis subgraphs
│   │   ├── routes/
│   │   │   ├── chat.py                 # /chat SSE endpoint
│   │   │   ├── search.py              # /search/vector|hybrid|graph
│   │   │   ├── definitions.py          # /definitions, /glossary
│   │   │   ├── standards.py            # /standards
│   │   │   ├── schema.py              # /schema
│   │   │   ├── feedback.py             # /feedback (LangSmith integration)
│   │   │   └── health.py              # /health
│   │   ├── prompts/
│   │   │   ├── catalog.py              # PromptCatalog with Hub caching
│   │   │   └── definitions.py          # Prompt text + Text2Cypher examples
│   │   └── evaluation/
│   │       ├── __init__.py             # Exports all evaluation utilities
│   │       ├── agentic_evaluators.py   # LangSmith evaluators for agentic RAG
│   │       ├── performance.py          # Subgraph performance tracking
│   │       ├── cost_analysis.py        # LLM cost tracking and estimation
│   │       ├── metrics.py              # Standard RAG evaluation metrics
│   │       └── domain_metrics.py       # Domain-specific metrics
│   ├── tests/                          # pytest suite (unit + integration)
│   ├── Dockerfile                      # Production container (Python 3.12)
│   └── pyproject.toml                  # Dependencies, Ruff, pytest config
│
├── frontend/
│   ├── src/
│   │   ├── App.jsx                     # Main layout (header, sidebar, chat)
│   │   ├── hooks/useSSEChat.js         # SSE streaming hook
│   │   └── components/
│   │       ├── chat/                   # MessageList, ChatInput, AssistantMessage
│   │       ├── metadata/              # EntityBadges, CypherDisplay, ResultsTable
│   │       ├── feedback/              # FeedbackBar, FeedbackModal
│   │       └── sidebar/               # Sidebar, quick-start templates
│   ├── Dockerfile                      # Dev/prod Node container
│   └── package.json                    # React 19, Vite 7, Tailwind 4
│
├── docker-compose.yml                  # Local dev: backend + frontend
├── railway.toml                        # Railway deployment config
└── LICENSE                             # MIT

许可证

麻省理工学院