feat: add FastAPI HTTP API layer
- Implement FastAPI server with health, collections, ingest, search, and delete endpoints - Add Pydantic request models for ingest and search - Add lazy singleton initialization for DB, embedder, and services - Support environment variable override for data dir and collection name - Add integration tests with TestClient and temp directory - Set TRANSFORMERS_OFFLINE/HF_HUB_OFFLINE for offline model loading in tests
This commit is contained in:
@@ -0,0 +1,137 @@
|
||||
"""FastAPI 服务层."""
|
||||
import os
|
||||
from pathlib import Path
|
||||
|
||||
from fastapi import FastAPI, HTTPException
|
||||
from pydantic import BaseModel
|
||||
|
||||
from src.core.config import load_config, EmbedConfig
|
||||
from src.core.db import VectorDB
|
||||
from src.core.embedder import create_embedder
|
||||
from src.core.ingest import DocumentIngestor
|
||||
from src.core.search import Searcher
|
||||
|
||||
|
||||
# -- 请求模型 --
|
||||
class IngestRequest(BaseModel):
|
||||
file_path: str | None = None
|
||||
content: str | None = None
|
||||
file_name: str | None = None
|
||||
|
||||
|
||||
class SearchRequest(BaseModel):
|
||||
query: str
|
||||
top_k: int = 10
|
||||
|
||||
|
||||
# -- 懒加载单例 --
|
||||
_db: VectorDB | None = None
|
||||
_embedder = None
|
||||
_searcher: Searcher | None = None
|
||||
_ingestor: DocumentIngestor | None = None
|
||||
|
||||
|
||||
def _get_db():
|
||||
global _db
|
||||
if _db is None:
|
||||
data_dir = os.getenv("MD_VECTOR_DB_DATA_DIR", "./data")
|
||||
_db = VectorDB(persist_dir=data_dir)
|
||||
return _db
|
||||
|
||||
|
||||
def _get_embedder():
|
||||
global _embedder
|
||||
if _embedder is None:
|
||||
# 先尝试从 config.yaml 加载, 失败则用默认 local
|
||||
try:
|
||||
cfg = load_config("config.yaml")
|
||||
embed_cfg = cfg.embed
|
||||
except Exception:
|
||||
embed_cfg = EmbedConfig(mode="local")
|
||||
_embedder = create_embedder(embed_cfg)
|
||||
return _embedder
|
||||
|
||||
|
||||
def _init_services():
|
||||
global _searcher, _ingestor
|
||||
collection = os.getenv("MD_VECTOR_DB_COLLECTION", "markdown_docs")
|
||||
try:
|
||||
cfg = load_config("config.yaml")
|
||||
collection = cfg.chroma.collection_name
|
||||
except Exception:
|
||||
pass
|
||||
_searcher = Searcher(_get_db(), _get_embedder(), collection)
|
||||
_ingestor = DocumentIngestor(_get_db(), _get_embedder(), collection)
|
||||
|
||||
|
||||
def _get_searcher():
|
||||
if _searcher is None:
|
||||
_init_services()
|
||||
return _searcher
|
||||
|
||||
|
||||
def _get_ingestor():
|
||||
if _ingestor is None:
|
||||
_init_services()
|
||||
return _ingestor
|
||||
|
||||
|
||||
# -- App --
|
||||
app = FastAPI(
|
||||
title="md-vector-db",
|
||||
description="Markdown 文档向量数据库 API",
|
||||
version="0.1.0",
|
||||
)
|
||||
|
||||
|
||||
@app.get("/api/v1/health")
|
||||
def health():
|
||||
return {"status": "ok"}
|
||||
|
||||
|
||||
@app.get("/api/v1/collections")
|
||||
def list_collections():
|
||||
searcher = _get_searcher()
|
||||
info = searcher.get_collection_info()
|
||||
sources = searcher.list_sources()
|
||||
return {"collections": [info], "sources": sources}
|
||||
|
||||
|
||||
@app.post("/api/v1/ingest")
|
||||
def ingest_document(req: IngestRequest):
|
||||
ingestor = _get_ingestor()
|
||||
try:
|
||||
if req.file_path:
|
||||
path = Path(req.file_path)
|
||||
if not path.exists():
|
||||
raise HTTPException(status_code=404, detail=f"文件不存在: {req.file_path}")
|
||||
count = ingestor.ingest_file(str(path))
|
||||
file_name = path.name
|
||||
elif req.content:
|
||||
file_name = req.file_name or "untitled.md"
|
||||
count = ingestor.ingest_content(req.content, file_name)
|
||||
else:
|
||||
raise HTTPException(
|
||||
status_code=400, detail="需要提供 file_path 或 content"
|
||||
)
|
||||
return {"status": "ok", "chunks": count, "file": file_name}
|
||||
except HTTPException:
|
||||
raise
|
||||
except Exception as e:
|
||||
raise HTTPException(status_code=500, detail=str(e))
|
||||
|
||||
|
||||
@app.post("/api/v1/search")
|
||||
def search_documents(req: SearchRequest):
|
||||
searcher = _get_searcher()
|
||||
results = searcher.search(req.query, top_k=req.top_k)
|
||||
return {"results": results}
|
||||
|
||||
|
||||
@app.delete("/api/v1/documents/{file_name}")
|
||||
def delete_document(file_name: str):
|
||||
searcher = _get_searcher()
|
||||
deleted = searcher.delete_by_source(file_name)
|
||||
if not deleted:
|
||||
raise HTTPException(status_code=404, detail=f"文档不存在: {file_name}")
|
||||
return {"status": "ok", "file": file_name}
|
||||
@@ -0,0 +1,92 @@
|
||||
"""API 端点集成测试."""
|
||||
import os
|
||||
import tempfile
|
||||
|
||||
import pytest
|
||||
from fastapi.testclient import TestClient
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def client():
|
||||
"""创建测试客户端（使用临时目录 + 本地嵌入模型）."""
|
||||
tmpdir = tempfile.mkdtemp()
|
||||
# 设置环境变量使 app 使用测试配置
|
||||
os.environ["MD_VECTOR_DB_DATA_DIR"] = tmpdir
|
||||
os.environ["MD_VECTOR_DB_COLLECTION"] = "test_api"
|
||||
# 离线模式: 模型已缓存, 无需联网
|
||||
os.environ["TRANSFORMERS_OFFLINE"] = "1"
|
||||
os.environ["HF_HUB_OFFLINE"] = "1"
|
||||
|
||||
from src.server.app import app
|
||||
|
||||
with TestClient(app) as c:
|
||||
yield c
|
||||
|
||||
|
||||
class TestHealthEndpoint:
|
||||
"""健康检查."""
|
||||
|
||||
def test_health_returns_ok(self, client):
|
||||
response = client.get("/api/v1/health")
|
||||
assert response.status_code == 200
|
||||
data = response.json()
|
||||
assert data["status"] == "ok"
|
||||
|
||||
|
||||
class TestCollectionEndpoint:
|
||||
"""Collection 端点."""
|
||||
|
||||
def test_list_collections(self, client):
|
||||
response = client.get("/api/v1/collections")
|
||||
assert response.status_code == 200
|
||||
data = response.json()
|
||||
assert "collections" in data
|
||||
|
||||
|
||||
class TestSearchEndpoint:
|
||||
"""搜索端点."""
|
||||
|
||||
def test_search_requires_query(self, client):
|
||||
response = client.post("/api/v1/search", json={})
|
||||
assert response.status_code == 422 # FastAPI 自动校验
|
||||
|
||||
def test_search_empty_collection(self, client):
|
||||
response = client.post(
|
||||
"/api/v1/search",
|
||||
json={"query": "test", "top_k": 5},
|
||||
)
|
||||
assert response.status_code == 200
|
||||
data = response.json()
|
||||
assert "results" in data
|
||||
assert data["results"] == []
|
||||
|
||||
|
||||
class TestIngestEndpoint:
|
||||
"""入库端点."""
|
||||
|
||||
def test_ingest_content(self, client):
|
||||
response = client.post(
|
||||
"/api/v1/ingest",
|
||||
json={
|
||||
"content": "# Test\nHello world.",
|
||||
"file_name": "test.md",
|
||||
},
|
||||
)
|
||||
assert response.status_code == 200
|
||||
data = response.json()
|
||||
assert data["status"] == "ok"
|
||||
assert data["chunks"] > 0
|
||||
|
||||
def test_ingest_then_search(self, client):
|
||||
"""入库后能检索到."""
|
||||
client.post(
|
||||
"/api/v1/ingest",
|
||||
json={"content": "# 配置说明\nChromaDB 配置很简单。", "file_name": "config.md"},
|
||||
)
|
||||
response = client.post(
|
||||
"/api/v1/search",
|
||||
json={"query": "配置", "top_k": 3},
|
||||
)
|
||||
assert response.status_code == 200
|
||||
data = response.json()
|
||||
assert len(data["results"]) > 0
|
||||
Reference in New Issue
Block a user