AI 全栈开发实战（1）：产品定义与架构设计 —— 做一个真正的 AI 知识库产品
·
前言
前面五篇我们学了 AI 应用开发的各项技术。从今天开始，我们要做一个真正的产品——一个可上线、可运营的 AI 知识库助手。
这个系列的目标不是"写 Demo"，而是从产品定义到部署上线的完整流程。每篇都有可运行的代码，最终交付一个可以给真实用户使用的产品。
1. 我们要做什么？
1.1 产品定位
产品名称：KNow（Knowledge Now）
一句话描述：让团队的知识文档变成 AI 可问答的智能知识库。
目标用户：中小团队、开发者、技术写作者
1.2 核心场景
场景一：新成员入职
新同事问：“我们的服务器部署流程是什么？”
KNow 回答：“登录跳板机 → 拉取最新代码 → 执行 deploy.sh → 检查健康检查接口…”
场景二：技术文档检索
开发者问：“用户模块的数据库表结构是怎样的？”
KNow 回答：“users 表有 id, email, password_hash, nickname, created_at 等字段…”
场景三：会议记录查询
成员问：“上个月的产品评审会结论是什么？”
KNow 回答：“结论是优先做知识库搜索功能，二期再做多租户…”
1.3 核心功能列表
MVP（第1-10篇）：
├── 📁 文档管理
│ ├── 上传 PDF/TXT/MD 文件
│ ├── 在线查看文档列表
│ ├── 删除和重新上传
│ └── 文档处理状态跟踪
├── 💬 智能问答
│ ├── 基于知识库的 RAG 问答
│ ├── 流式输出（打字机效果）
│ ├── 对话历史记录
│ └── 引用来源标注
├── 👤 用户系统
│ ├── 注册/登录
│ ├── API Key 管理
│ └── 个人设置
└── 🔧 管理后台
├── 知识库概览
├── 使用量统计
└── 系统设置
V2（扩展方向）：
├── 🌐 多知识库
├── 🤝 团队协作
├── 🔗 第三方集成（飞书/钉钉/企微）
├── 📊 分析仪表盘
└── 🔌 OpenAI API 兼容接口
2. 技术栈选型
2.1 选型原则
- 实用优先——选我用过、用过的技术，不追新
- 成本可控——MVP 阶段全部用免费/开源方案
- 易于部署——一个 docker-compose 就能跑起来
2.2 技术栈全景
┌─────────────────────────────────────────────────┐
│ 前端 │
│ React 19 + Vite + TailwindCSS + shadcn/ui │
│ react-markdown + SSE 流式渲染 │
├─────────────────────────────────────────────────┤
│ API 层 │
│ FastAPI + SQLAlchemy + Alembic │
│ Celery（异步任务）+ Redis（缓存/队列） │
├─────────────────────────────────────────────────┤
│ AI 引擎 │
│ LangChain / LlamaIndex（RAG 编排） │
│ Qdrant（向量数据库） │
│ BGE 系列（Embedding + Re-rank） │
├─────────────────────────────────────────────────┤
│ 数据层 │
│ PostgreSQL（业务数据） │
│ Redis（缓存 + 会话 + 任务队列） │
│ MinIO（文件存储，S3 兼容） │
├─────────────────────────────────────────────────┤
│ 部署层 │
│ Docker + Docker Compose │
│ Nginx（反向代理 + SSL） │
│ GitHub Actions（CI/CD） │
└─────────────────────────────────────────────────┘
2.3 为什么选这些技术
| 技术 | 为什么选 | 不选什么 |
|---|---|---|
| React 19 | 生态最成熟，shadcn/ui 省去 UI 开发时间 | Vue 也可以 |
| FastAPI | 异步支持好，自动生成 OpenAPI 文档 | Flask（太轻）、Django（太重） |
| PostgreSQL | 功能强，支持 pgvector 扩展 | MySQL（功能少） |
| Qdrant | 性能好，部署简单（单二进制），Rust 实现 | Milvus（太重）、Chroma（太弱） |
| MinIO | S3 兼容，Docker 一键部署 | 自建文件系统（不持久） |
| Celery | 稳定成熟的异步任务队列 | Redis Queue（功能少） |
2.4 项目目录结构
know/
├── docker-compose.yml # 所有服务编排
├── .env.example # 环境变量模板
├── backend/
│ ├── Dockerfile
│ ├── requirements.txt
│ ├── alembic.ini
│ ├── app/
│ │ ├── main.py # FastAPI 入口
│ │ ├── config.py # 配置管理
│ │ ├── models/ # SQLAlchemy 模型
│ │ ├── routers/ # API 路由
│ │ ├── services/ # 业务逻辑
│ │ ├── tasks/ # Celery 任务
│ │ └── schemas/ # Pydantic Schema
│ └── migrations/ # Alembic 迁移
├── frontend/
│ ├── Dockerfile
│ ├── package.json
│ ├── src/
│ │ ├── components/ # UI 组件
│ │ ├── pages/ # 页面
│ │ ├── hooks/ # 自定义 Hook
│ │ ├── api/ # API 客户端
│ │ └── lib/ # 工具函数
│ └── public/
└── docs/ # 文档
3. 数据库设计（MVP）
3.1 ER 图
users ──────┬── knowledge_bases ──┬── documents
│ │
│ └── document_chunks
│
└── conversations ──┬── messages
│
└── citations
3.2 核心表定义
users（用户表）
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
email VARCHAR(255) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
nickname VARCHAR(100) NOT NULL,
avatar_url VARCHAR(500),
is_active BOOLEAN DEFAULT TRUE,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
knowledge_bases（知识库表）
CREATE TABLE knowledge_bases (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID NOT NULL REFERENCES users(id),
name VARCHAR(200) NOT NULL,
description TEXT,
embedding_model VARCHAR(100) DEFAULT 'BAAI/bge-small-zh-v1.5',
chunk_size INT DEFAULT 512,
chunk_overlap INT DEFAULT 128,
document_count INT DEFAULT 0,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
documents（文档表）
CREATE TABLE documents (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
knowledge_base_id UUID NOT NULL REFERENCES knowledge_bases(id),
filename VARCHAR(500) NOT NULL,
file_path VARCHAR(1000) NOT NULL,
file_size INT NOT NULL,
file_type VARCHAR(20) NOT NULL, -- pdf/txt/md
status VARCHAR(20) DEFAULT 'pending', -- pending/processing/ready/failed
chunk_count INT DEFAULT 0,
error_message TEXT,
created_at TIMESTAMP DEFAULT NOW()
);
conversations（对话表）
CREATE TABLE conversations (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
user_id UUID NOT NULL REFERENCES users(id),
knowledge_base_id UUID REFERENCES knowledge_bases(id),
title VARCHAR(500) DEFAULT '新对话',
message_count INT DEFAULT 0,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
CREATE TABLE messages (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
conversation_id UUID NOT NULL REFERENCES conversations(id),
role VARCHAR(20) NOT NULL, -- user/assistant
content TEXT NOT NULL,
tokens_used INT DEFAULT 0,
created_at TIMESTAMP DEFAULT NOW()
);
CREATE TABLE citations (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
message_id UUID NOT NULL REFERENCES messages(id),
document_id UUID NOT NULL REFERENCES documents(id),
chunk_text TEXT,
score FLOAT,
created_at TIMESTAMP DEFAULT NOW()
);
3.3 API 设计（MVP）
# 用户
POST /api/auth/register # 注册
POST /api/auth/login # 登录
GET /api/auth/me # 获取当前用户
# 知识库
POST /api/knowledge-bases # 创建知识库
GET /api/knowledge-bases # 知识库列表
GET /api/knowledge-bases/:id # 知识库详情
DELETE /api/knowledge-bases/:id # 删除知识库
# 文档
POST /api/knowledge-bases/:id/documents # 上传文档
GET /api/knowledge-bases/:id/documents # 文档列表
DELETE /api/knowledge-bases/:id/documents/:doc # 删除文档
# 对话
POST /api/conversations # 创建对话
GET /api/conversations # 对话列表
POST /api/conversations/:id/messages # 发送消息（流式）
GET /api/conversations/:id/messages # 获取消息历史
DELETE /api/conversations/:id # 删除对话
# 统计
GET /api/stats # 使用量统计
4. 技术架构与流程
4.1 文档处理流程
用户上传 PDF
│
▼
FastAPI 接收文件 → 存入 MinIO → 创建 Document 记录
│
▼
Celery 异步任务处理：
1. 解析文档（PDF→文本）
2. 文本切分（Chunk）
3. Embedding 向量化
4. 存入 Qdrant
5. 更新 Document 状态为 ready
│
▼
用户可以提问
4.2 问答流程
用户提问
│
▼
1. 获取知识库的 Qdrant collection
2. Query Embedding
3. Qdrant 向量检索（Top-10）
4. Cross-Encoder Re-rank（取 Top-3）
5. 构建 Prompt（系统指令 + 检索结果 + 用户问题）
6. LLM 流式生成回答
7. 保存对话记录 + 引用来源
│
▼
流式返回给前端
4.3 前端页面结构（MVP）
/login # 登录页
/register # 注册页
/dashboard # 仪表盘
/knowledge-bases # 知识库列表
/knowledge-bases/:id # 知识库详情（文件管理）
/chat # 对话页
/chat/:id # 对话详情
/settings # 个人设置
5. 开发计划（对应系列篇目）
| 篇目 | 内容 | 交付物 |
|---|---|---|
| 第1篇 | 产品定义与架构设计 | ✅ 本文 |
| 第2篇 | 技术选型与项目初始化 | docker-compose + 项目骨架 |
| 第3篇 | 用户系统（注册/登录/JWT） | 完整用户模块 |
| 第4篇 | 知识库与文档管理 | 上传/列表/删除 API |
| 第5篇 | 文档处理 Pipeline | PDF 解析 + Chunk + Embedding |
| 第6篇 | 向量检索与 RAG 问答 | 问答 API + 流式输出 |
| 第7篇 | 前端开发（一）——项目骨架与页面框架 | React 项目 + 页面路由 |
| 第8篇 | 前端开发（二）——对话界面与流式渲染 | 对话 UI + 打字机效果 |
| 第9篇 | 前端开发（三）——文件管理与知识库 UI | 文件上传 + 知识库管理界面 |
| 第10篇 | 对话历史与管理 | 历史列表 + 上下文管理 |
| 第11篇 | 用户 API Key 与用量统计 | API Key + 统计模块 |
| 第12篇 | Docker 部署与线上发布 | docker-compose + Nginx |
| 第13篇 | CI/CD 与自动化测试 | GitHub Actions + 测试 |
| 第14篇 | 性能优化与监控 | 缓存、日志、告警 |
| 第15篇 | 产品化与持续迭代 | 上线 checklist + 反馈闭环 |
总结
今天我们完成了 KNow 产品的定义和架构设计。核心决策：
- 做什么：一个 AI 知识库助手，让文档变可问答
- 技术栈：React + FastAPI + PostgreSQL + Qdrant + MinIO
- 核心流程：上传文档 → 自动处理 → 智能问答
下一篇我们将开始动手——初始化项目结构、配置 Docker 环境、搭建前后端骨架。
本文是 《AI 全栈开发实战——做一个真正的产品》 系列的第 1 篇。
系列目录：
- ✅ 产品定义与架构设计 ← 你在这里
- 📝 技术选型与项目初始化
- 📝 用户系统
- 📝 知识库与文档管理
- 📝 文档处理 Pipeline
- 📝 向量检索与 RAG 问答
7-9. 📝 前端开发（三篇）- 📝 对话历史与管理
- 📝 API Key 与用量统计
- 📝 Docker 部署
- 📝 CI/CD 与测试
- 📝 性能优化与监控
- 📝 产品化与持续迭代
本文由 Zyentor（智元界） 原创发布
本文发布于 Zyentor（智元界） —— AI 开发者社区
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
7
0- 0
已为社区贡献13条内容
所有评论(0)