From 0191eea378524dacd7d2836f5497389de44c69fa Mon Sep 17 00:00:00 2001
From: yumoqing <yumoqing@gmail.com>
Date: Tue, 21 Jul 2026 17:37:04 +0800
Subject: [PATCH] docs: complete README with architecture, API, and deployment
 guide

---
 README.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 99 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 716a218..a77d4a2 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,100 @@
-# rag-pipeline
+# RAG Pipeline — 可插拔 RAG 编排引擎
 
+## 概述
+
+RAG Pipeline 是一个可插拔的 RAG (检索增强生成) 编排服务，支持知识图谱增强的多模态检索。通过插件注册表，所有底层引擎（向量化、向量库、图数据库、重排器）均可替换。
+
+## 架构
+
+```
+                    ┌─────────────────┐
+                    │  RAG Pipeline   │
+                    │   (9093 CPU)    │
+                    └────────┬────────┘
+                             │
+          ┌──────────────────┼──────────────────┐
+          │                  │                  │
+    ┌─────▼─────┐     ┌─────▼─────┐     ┌─────▼─────┐
+    │   CLIP    │     │    VDB    │     │  Graph    │
+    │   9086    │     │   8886    │     │   9092    │
+    │ GPU 2     │     │   CPU     │     │   CPU     │
+    └───────────┘     └───────────┘     └───────────┘
+          │                  │                  │
+    ┌─────▼─────┐     ┌─────▼─────┐     
+    │BGE Rerank │     │   LLM     │     
+    │   9090    │     │harnessed  │     
+    └───────────┘     └───────────┘     
+```
+
+## 插件槽位
+
+| 槽位 | 当前实现 | 可替换为 |
+|------|---------|---------|
+| embedding | CLIP-ViT-H/14 (9086) | BGE-M3, OpenAI embedding |
+| vdb | Milvus VDB (8886) | Qdrant, Weaviate |
+| graph | NetworkX (9092) | FalkorDB, Neo4j |
+| reranker | BGE-Reranker (9090) | Cohere, LLM rerank |
+| llm | harnessed_agent | 任意 LLM |
+| chunker | recursive/sentence | 自定义分块策略 |
+| extractor | LLM-structured | spaCy, GraphRAG |
+| retriever | hybrid/vector_only | 自定义检索策略 |
+| face | InsightFace (9091) | FaceNet, DeepFace |
+
+## Pipeline 配置
+
+### kg-rag-standard（标准版）
+- CLIP embedding + Milvus + NetworkX 图 + BGE Rerank
+- 向量召回 + 图扩展 + RRF 融合 + 精排
+
+### kg-rag-lite（轻量版）
+- CLIP embedding + Milvus + BGE Rerank
+- 纯向量检索，无图谱
+
+## API
+
+### GET /api/status — 服务状态和可用插件列表
+
+### POST /api/ingest — 入库文档
+```json
+{"document": "文本内容...", "pipeline": "kg-rag-standard", "collection": "knowledge", "graph_name": "knowledge"}
+```
+流程: 分块 → CLIP embedding → VDB 存储 → 实体抽取 → 图存储
+
+### POST /api/search — 混合检索
+```json
+{"query": "搜索问题", "pipeline": "kg-rag-standard", "top_k": 5}
+```
+流程: CLIP embed → VDB 向量召回 → 图扩展 → RRF 融合 → BGE Rerank → 答案生成
+
+### GET/POST /api/pipelines — 管理 pipeline 配置
+
+### GET /api/plugins — 列出所有可用插件及状态
+
+## 部署
+
+```bash
+cd /data/ymq/rag-pipeline
+bash build.sh deploy
+bash build.sh stop
+bash build.sh status
+```
+
+## 端到端测试
+
+```bash
+curl -X POST http://localhost:9093/api/ingest \
+  -H "Content-Type: application/json" \
+  -d '{"document":"张三在ABC公司担任技术总监，他和李四是同事关系。"}'
+
+curl -X POST http://localhost:9093/api/search \
+  -H "Content-Type: application/json" \
+  -d '{"query":"张三在哪家公司工作？"}'
+```
+
+## 端口
+
+9093 (CPU only)
+
+## Git
+
+git@git.opencomputing.cn:yumoqing/rag-pipeline.git