Kotaemon微服务改造：拆分组件实现高可用架构升级

1. 背景与挑战

Kotaemon 是由 Cinnamon 开发的开源项目，定位为一个面向文档问答（DocQA）场景的 RAG（Retrieval-Augmented Generation）前端界面。它不仅服务于终端用户进行知识库问答交互，还支持开发者构建和调试自定义的 RAG 流程。随着社区使用量上升，单体架构下的系统瓶颈逐渐显现：

模块耦合严重：前端、检索逻辑、模型调用、向量化处理等全部集成在单一服务中，导致维护困难。
扩展性差：当某一部分负载升高（如向量化任务激增），无法独立扩容，资源利用率低。
可用性风险高：任一组件异常可能影响整体服务稳定性。

为提升系统的可维护性、弹性和容错能力，我们对 Kotaemon 进行了微服务化改造，通过组件解耦实现高可用架构升级。

2. 微服务拆分设计

2.1 拆分原则

遵循“单一职责”与“领域驱动设计”（DDD）思想，将原单体应用按功能边界划分为以下核心微服务：

服务名称	职责说明
`kotaemon-ui`	前端界面服务，负责用户交互与页面渲染
`kotaemon-api-gateway`	API 网关，统一入口，路由转发与认证
`kotaemon-doc-processor`	文档解析与预处理服务
`kotaemon-vector-store`	向量存储管理，对接 Chroma/Pinecone 等
`kotaemon-retriever`	检索服务，执行语义搜索与结果排序
`kotaemon-llm-proxy`	大模型代理层，兼容 Ollama、OpenAI、HuggingFace 等

每个服务独立部署、独立数据库（或数据隔离），通过 RESTful API 或异步消息通信。

2.2 架构演进对比

改造前：单体架构

+--------------------------------------------------+ | Kotaemon Monolith | | UI + API + Retrieval + Vectorization + LLM | +--------------------------------------------------+ ↓ 单一进程，共享内存

改造后：微服务架构

+-----------------+ | kotaemon-ui | +--------+--------+ | +--------v--------+ | api-gateway | +--------+--------+ / | \ v v v +---------------+ +------------------+ +------------------+ | doc-processor | | vector-store | | llm-proxy | +---------------+ +------------------+ +------------------+ | v +------------------+ | retriever | +------------------+

该结构提升了系统的横向扩展能力和故障隔离性。

3. 关键组件实现细节

3.1 API 网关统一入口

采用 FastAPI 实现轻量级网关服务kotaemon-api-gateway，承担以下职责：

请求路由：根据路径前缀转发至对应微服务
认证鉴权：JWT 校验用户身份
日志记录：统一访问日志采集
限流熔断：防止突发流量冲击下游服务

from fastapi import FastAPI, Request, HTTPException from starlette.middleware.base import BaseHTTPMiddleware import httpx app = FastAPI() # 服务地址映射 SERVICES = { "/docs": "http://doc-processor:8001", "/vector": "http://vector-store:8002", "/query": "http://retriever:8003", "/model": "http://llm-proxy:8004" } @app.api_route("/{path:path}", methods=["GET", "POST", "PUT", "DELETE"]) async def proxy(path: str, request: Request): # 路由匹配 for prefix, url in SERVICES.items(): if path.startswith(prefix): client = httpx.AsyncClient(base_url=url) try: resp = await client.request( method=request.method, url=f"/{path}", content=await request.body(), headers=dict(request.headers), ) return resp.json() except Exception as e: raise HTTPException(status_code=500, detail=str(e)) raise HTTPException(status_code=404, detail="Service not found")

优势：解耦客户端与后端服务，便于灰度发布与监控。

3.2 文档处理服务独立化

kotaemon-doc-processor负责接收上传文件并完成以下流程：

文件类型识别（PDF/DOCX/TXT）
使用pypdf、python-docx等库提取文本
分块（chunking）策略配置（固定长度或基于语义）
返回清洗后的文本片段供向量化使用

关键代码示例：

def split_text(text: str, chunk_size: int = 512, overlap: int = 50) -> List[str]: words = text.split() chunks = [] i = 0 while i < len(words): chunk = " ".join(words[i:i + chunk_size]) chunks.append(chunk) i += chunk_size - overlap return chunks

该服务可独立扩容以应对批量导入高峰。

3.3 向量存储抽象层设计

kotaemon-vector-store提供统一接口，屏蔽底层向量数据库差异：

class VectorStore: def add_documents(self, docs: List[Document], embeddings: List[List[float]]): raise NotImplementedError def similarity_search(self, query_vector: List[float], k: int = 5) -> List[Document]: raise NotImplementedError class ChromaVectorStore(VectorStore): def __init__(self, collection_name: str): import chromadb self.client = chromadb.Client() self.collection = self.client.get_or_create_collection(collection_name) def add_documents(self, docs, embeddings): self.collection.add( embeddings=embeddings, documents=[d.text for d in docs], metadatas=[d.metadata for d in docs] )

支持运行时切换不同引擎（Chroma、Pinecone、Weaviate），增强灵活性。

3.4 模型代理层兼容多后端

kotaemon-llm-proxy统一接入多种 LLM 提供商，适配 OpenAI 兼容接口：

async def generate(prompt: str, model: str = "llama3"): if model.startswith("ollama/"): return await call_ollama_api(prompt, model.replace("ollama/", "")) elif model.startswith("openai/"): return await call_openai_api(prompt, model.replace("openai/", "")) else: raise ValueError("Unsupported model provider") async def call_ollama_api(prompt: str, model: str): async with httpx.AsyncClient() as client: response = await client.post( "http://ollama:11434/api/generate", json={"model": model, "prompt": prompt, "stream": False} ) return response.json()["response"]

此设计使得前端无需感知具体模型来源，便于测试与替换。

4. 高可用保障措施

4.1 容器化与编排部署

所有微服务均打包为 Docker 镜像，并通过 Kubernetes 进行编排管理：

# 示例：kotaemon-retriever Dockerfile FROM python:3.10-slim WORKDIR /app COPY requirements.txt . RUN pip install -r requirements.txt COPY . . CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8003"]

Kubernetes 配置确保：

多副本部署（replicas ≥ 2）
健康检查（liveness/readiness probe）
自动重启与负载均衡

4.2 异常隔离与降级策略

引入 Circuit Breaker 模式防止雪崩效应。例如，在api-gateway中集成circuitbreaker库：

from circuitbreaker import circuit @circuit(failure_threshold=3, recovery_timeout=60) async def resilient_call(service_url, payload): async with httpx.AsyncClient() as client: resp = await client.post(service_url, json=payload) resp.raise_for_status() return resp.json()

当某服务连续失败超过阈值，自动进入熔断状态，避免连锁故障。