从零构建智能知识库：项目概览与环境搭建

2026-03-24 · 14 分钟阅读

在接下来的几篇文章中，我们将从零开始，手把手构建一个基于 OpenClaw + RAG的企业级智能知识库系统。它能够支持多格式文档上传，将内容存入向量数据库，并通过大语言模型提供精准、无幻觉的问答服务。

这篇文章，我会先帮你理清整体架构、技术选型，并搭建好完整的开发环境。

摘要

  • 理解企业级智能知识库的核心痛点与 RAG 技术的解决方案
  • 知道为什么选择 OpenClaw + FastAPI + Node.js 这套组合，而不是纯 LangChain 方案
  • 掌握 OpenClaw AI 网关的基本概念与核心优势
  • 在本地创建好 Python 和 Node.js 的开发环境
  • 成功启动 FastAPI 服务、OpenClaw 网关和 Node.js 前端服务，为后续开发铺路

1. 什么是企业级智能知识库？为什么我们需要它？

1.1 传统知识库的痛点

在数字化转型的今天，几乎每个企业都积累了海量的文档资料：产品手册、技术文档、培训材料、客户案例、规章制度……但这些宝贵的知识资产往往处于"沉睡"状态：

  • 查找困难：员工需要在多个系统、数百个文件夹中翻找信息，平均每天浪费1-2小时
  • 知识断层：老员工离职带走核心知识，新员工上手慢
  • 信息不一致：不同版本的文档同时存在，导致错误决策
  • 大模型幻觉：直接使用通用大模型回答企业内部问题，经常出现"一本正经地胡说八道"

1.2 RAG 技术如何解决这些问题

RAG（Retrieval-Augmented Generation，检索增强生成）是让大语言模型"按需翻阅参考资料"的技术。它的核心流程是：

  1. 文档加载与切块：将原始文档（PDF、Word、Markdown 等）拆成适合模型处理的小段
  2. 向量化：用 Embedding 模型把每段文本转成向量，存入向量数据库
  3. 检索：用户提问时，把问题也转成向量，从数据库中找出语义最相关的若干段落
  4. 生成：把检索到的内容作为上下文，连同问题一起发给大模型，生成基于事实的答案

这样，大模型就不必"死记硬背"所有知识，而是可以引用最新、最准确的企业内部资料，从根本上解决幻觉问题。

2. 技术选型深度对比：为什么选择这套组合？

在项目开始前，我们调研了市场上几乎所有主流的 AI 应用开发技术栈，并进行了全面的对比分析。

2.1 传统方案的局限性

方案一：纯 LangChain/LlamaIndex 原生开发

  • 优点：灵活性高，社区生态丰富
  • 缺点：代码量巨大，重复造轮子；缺乏统一的会话管理；生产级特性需要自己实现；模型切换成本高

方案二：使用现成的知识库 SaaS 服务

  • 优点：开箱即用，无需开发
  • 缺点：数据安全风险；定制化能力差；成本高昂；无法与企业现有系统深度集成

方案三：基于 ChatGPT 插件或 Claude Artifacts 开发

  • 优点：开发简单，利用大模型原生能力
  • 缺点：完全依赖第三方平台；数据必须经过大模型服务商；功能受限；无法私有化部署

2.2 我们的技术栈：OpenClaw + RAG + FastAPI + Node.js

经过反复权衡，我们最终选择了这个技术组合，它完美平衡了开发效率、功能强大性、生产可靠性和数据安全性。

我们整体的技术栈可以用一张图概括：

┌─────────────────────────────────────────────────────────┐
│                      前端层 (Node.js + React)            │
│  登录注册 │ 文档管理 │ 智能问答 │ 系统设置 │ 统计分析    │
└───────────────────────────┬─────────────────────────────┘
                            │
┌───────────────────────────┼─────────────────────────────┐
│                      业务层 (FastAPI)                    │
│  用户认证 │ 文档处理 │ 向量存储 │ 权限控制 │ 日志管理    │
└───────────────────────────┬─────────────────────────────┘
                            │
┌───────────────────────────┼─────────────────────────────┐
│                      AI网关层 (OpenClaw)                 │
│  模型管理 │ 会话管理 │ 技能调度 │ 流式输出 │ 错误处理    │
│                           │                             │
│  ┌─────────────────────┐  │  ┌─────────────────────┐    │
│  │   Claude 3 Opus     │  │  │   RAG检索技能       │    │
│  │   GPT-4o            │<─┼─>│   重排序技能        │    │
│  │   本地Ollama模型    │  │  │   多模态技能        │    │
│  └─────────────────────┘  │  └─────────────────────┘    │
└───────────────────────────┬─────────────────────────────┘
                            │
┌───────────────────────────┼─────────────────────────────┐
│                      数据层                              │
│  PostgreSQL │ Chroma/Pinecone │ 文件存储 │ 缓存系统     │
└─────────────────────────────────────────────────────────┘

各组件具体分工如下：

2.2.1 FastAPI —— 业务逻辑后端

  • 负责所有非 AI 相关的业务任务：用户认证、文档上传与解析、向量存储、权限控制
  • 提供 RESTful API，例如 POST /api/documents/upload、GET /api/documents
  • 使用 FastAPI 是因为它异步性能出色、自动生成文档，且与 Python AI 生态无缝衔接

2.2.2 Node.js + React —— 前端用户界面

  • 提供一个现代化的 Web 界面，让用户上传文档、提问和查看结果
  • 处理流式输出，实现流畅的打字机效果
  • 我们选用 Vite + React + TypeScript + Ant Design，这是目前最成熟的前端技术栈之一

2.2.3 OpenClaw —— AI 智能体网关（核心）

  • 统一管理所有大模型调用，一行配置切换 Claude/GPT/Gemini/本地模型
  • 基于 MCP（Model Context Protocol）协议的模块化技能系统，集成 RAG 只需几十行代码
  • 内置生产级会话管理、状态同步、历史消息管理
  • 原生支持 SSE 和 WebSocket 流式输出，打字机效果一行代码实现

2.3 OpenClaw 的独特优势

OpenClaw 是整个架构中最关键的组件，也是我们选择这个技术栈的核心理由。它不是另一个 LangChain，而是一个更高层次的AI 智能体运行时与网关平台。

一句话总结：LangChain 让你能构建 AI 应用，OpenClaw 让你能快速构建并在生产环境运行AI 应用。

3. 本地开发环境准备

开始之前，请确保你的机器上已经安装：

  • Python 3.11+（推荐 3.11 或 3.12，3.13 部分依赖可能有兼容性问题）
  • Node.js 20+（LTS 版本，推荐 20.12+）
  • pnpm（比 npm/yarn 更快更高效）
  • Git（版本控制）
  • （可选）Docker Desktop，用于后续部署和向量数据库容器

你可以用以下命令检查：

python --version
node --version
pnpm --version
git --version

如果 pnpm 未安装，可以使用以下命令安装：

npm install -g pnpm

4. 项目初始化

我们将在一个大的仓库下包含三个子目录：backend/（FastAPI）、openclaw/（OpenClaw 配置与技能）和 frontend/（Node.js + React）。

4.1 创建项目目录

mkdir enterprise-knowledge-base && cd enterprise-knowledge-base
mkdir backend openclaw frontend
git init

创建 .gitignore 文件：

# Python
__pycache__/
*.py[cod]
*$py.class
venv/
.env

# Node.js
node_modules/
dist/
.DS_Store

4.2 搭建 FastAPI 后端

进入 backend 目录，创建虚拟环境并安装基本依赖：

cd backend
python -m venv venv
source venv/bin/activate   # Windows 使用 venv\Scripts\activate

pip install fastapi uvicorn[standard] python-dotenv python-multipart

新建 main.py：

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI(title="企业级智能知识库 API", version="0.1.0")

# 配置 CORS
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # 开发环境允许所有来源，生产环境请限制为具体域名
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

@app.get("/")
async def root():
    return {"message": "企业级智能知识库后端已启动", "version": "0.1.0"}

@app.get("/api/health")
async def health_check():
    return {"status": "healthy"}

现在可以启动服务测试：

uvicorn main:app --reload --port 8000

打开浏览器访问 http://localhost:8000，你应该能看到返回的 JSON 消息。
FastAPI 还自带交互式文档，访问 http://localhost:8000/docs 查看。

4.3 搭建 OpenClaw AI 网关

另开一个终端，进入 openclaw 目录：

cd ../openclaw
pnpm init -y
pnpm add openclaw

在 package.json 中添加脚本：

"scripts": {
  "start": "openclaw start",
  "init": "openclaw init"
}

初始化 OpenClaw 配置：

pnpm run init

按照提示输入你的 Claude API Key（也可以稍后在配置文件中修改），选择默认模型为 claude-3-sonnet-20240229。

启动 OpenClaw 网关：

pnpm run start

OpenClaw 会在本地 127.0.0.1:18789 端口启动，同时会自动打开 Web 管理界面。你可以在界面中进行简单的对话测试，确认 API Key 配置正确。

4.4 搭建 Node.js 前端

再开一个终端，进入 frontend 目录：

cd ../frontend
pnpm create vite@latest . -- --template react-ts
pnpm install
pnpm add axios antd @ant-design/icons zustand react-router-dom

修改 src/App.tsx：

import { Button, Space, Typography } from 'antd';
import { useState } from 'react';
import axios from 'axios';

const { Title, Text } = Typography;

function App() {
  const [backendStatus, setBackendStatus] = useState<string>('检查中...');
  const [openclawStatus, setOpenclawStatus] = useState<string>('检查中...');

  const checkBackend = async () => {
    try {
      const response = await axios.get('http://localhost:8000/api/health');
      setBackendStatus(`正常 (${response.data.status})`);
    } catch (error) {
      setBackendStatus('连接失败');
    }
  };

  const checkOpenClaw = async () => {
    try {
      const response = await axios.get('http://localhost:127.0.0.1:18789/api/health');
      setOpenclawStatus('正常');
    } catch (error) {
      setOpenclawStatus('连接失败');
    }
  };

  return (
    <div style={{ padding: '50px' }}>
      <Title level={2}>企业级智能知识库</Title>
      <Space direction="vertical" size="large" style={{ marginTop: '30px' }}>
        <div>
          <Text strong>后端服务状态：</Text>
          <Text>{backendStatus}</Text>
          <Button onClick={checkBackend} style={{ marginLeft: '10px' }}>刷新</Button>
        </div>
        <div>
          <Text strong>OpenClaw 网关状态：</Text>
          <Text>{openclawStatus}</Text>
          <Button onClick={checkOpenClaw} style={{ marginLeft: '10px' }}>刷新</Button>
        </div>
      </Space>
    </div>
  );
}

export default App;

启动前端开发服务器：

pnpm run dev

访问 http://localhost:5173，你应该能看到前端页面，并且可以检查后端和 OpenClaw 网关的连接状态。

5. 项目结构总览

至此，你的项目目录应该像这样：

enterprise-knowledge-base/
├── .gitignore
├── backend/
│   ├── venv/
│   ├── main.py
│   └── requirements.txt   (后续生成)
├── openclaw/
│   ├── node_modules/
│   ├── package.json
│   └── .claw/             (OpenClaw 自动生成的配置目录)
└── frontend/
    ├── node_modules/
    ├── src/
    │   ├── App.tsx
    │   └── main.tsx
    ├── index.html
    ├── package.json
    └── tsconfig.json

三个服务都成功跑起来了，意味着我们的开发环境已经完全就绪。

6. 小结

本篇文章我们完成了以下事情：

  • 分析了企业级智能知识库的核心痛点与 RAG 技术的解决方案
  • 对比了不同技术栈的优缺点，明确了 OpenClaw + FastAPI + Node.js 的技术方案
  • 理解了 OpenClaw 作为 AI 网关的核心定位与独特优势
  • 搭建了完整的本地开发环境，包括 Python 虚拟环境和 Node.js 环境
  • 成功启动了 FastAPI 后端服务、OpenClaw AI 网关和 React 前端服务
  • 为后续的开发打下了坚实的基础

需要我帮你生成完整的 requirements.txt 文件和优化后的项目结构模板吗？