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 选型原则

1. 实用优先——选我用过、用过的技术，不追新
2. 成本可控——MVP 阶段全部用免费/开源方案
3. 易于部署——一个 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 为什么选这些技术

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（用户表）

CREATETABLEusers(id UUIDPRIMARYKEYDEFAULTgen_random_uuid(),emailVARCHAR(255)UNIQUENOTNULL,password_hashVARCHAR(255)NOTNULL,nicknameVARCHAR(100)NOTNULL,avatar_urlVARCHAR(500),is_activeBOOLEANDEFAULTTRUE,created_atTIMESTAMPDEFAULTNOW(),updated_atTIMESTAMPDEFAULTNOW());

knowledge_bases（知识库表）

CREATETABLEknowledge_bases(id UUIDPRIMARYKEYDEFAULTgen_random_uuid(),user_id UUIDNOTNULLREFERENCESusers(id),nameVARCHAR(200)NOTNULL,descriptionTEXT,embedding_modelVARCHAR(100)DEFAULT'BAAI/bge-small-zh-v1.5',chunk_sizeINTDEFAULT512,chunk_overlapINTDEFAULT128,document_countINTDEFAULT0,created_atTIMESTAMPDEFAULTNOW(),updated_atTIMESTAMPDEFAULTNOW());

documents（文档表）

CREATETABLEdocuments(id UUIDPRIMARYKEYDEFAULTgen_random_uuid(),knowledge_base_id UUIDNOTNULLREFERENCESknowledge_bases(id),filenameVARCHAR(500)NOTNULL,file_pathVARCHAR(1000)NOTNULL,file_sizeINTNOTNULL,file_typeVARCHAR(20)NOTNULL,-- pdf/txt/mdstatusVARCHAR(20)DEFAULT'pending',-- pending/processing/ready/failedchunk_countINTDEFAULT0,error_messageTEXT,created_atTIMESTAMPDEFAULTNOW());

conversations（对话表）

CREATETABLEconversations(id UUIDPRIMARYKEYDEFAULTgen_random_uuid(),user_id UUIDNOTNULLREFERENCESusers(id),knowledge_base_id UUIDREFERENCESknowledge_bases(id),titleVARCHAR(500)DEFAULT'新对话',message_countINTDEFAULT0,created_atTIMESTAMPDEFAULTNOW(),updated_atTIMESTAMPDEFAULTNOW());CREATETABLEmessages(id UUIDPRIMARYKEYDEFAULTgen_random_uuid(),conversation_id UUIDNOTNULLREFERENCESconversations(id),roleVARCHAR(20)NOTNULL,-- user/assistantcontentTEXTNOTNULL,tokens_usedINTDEFAULT0,created_atTIMESTAMPDEFAULTNOW());CREATETABLEcitations(id UUIDPRIMARYKEYDEFAULTgen_random_uuid(),message_id UUIDNOTNULLREFERENCESmessages(id),document_id UUIDNOTNULLREFERENCESdocuments(id),chunk_textTEXT,scoreFLOAT,created_atTIMESTAMPDEFAULTNOW());

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. 开发计划（对应系列篇目）

总结

今天我们完成了 KNow 产品的定义和架构设计。核心决策：

• 做什么：一个 AI 知识库助手，让文档变可问答
• 技术栈：React + FastAPI + PostgreSQL + Qdrant + MinIO
• 核心流程：上传文档 → 自动处理 → 智能问答

下一篇我们将开始动手——初始化项目结构、配置 Docker 环境、搭建前后端骨架。

本文是《AI 全栈开发实战——做一个真正的产品》系列的第 1 篇。
系列目录：

1. ✅ 产品定义与架构设计 ← 你在这里
2. 📝 技术选型与项目初始化
3. 📝 用户系统
4. 📝 知识库与文档管理
5. 📝 文档处理 Pipeline
6. 📝 向量检索与 RAG 问答
   7-9. 📝 前端开发（三篇）
7. 📝 对话历史与管理
8. 📝 API Key 与用量统计
9. 📝 Docker 部署
10. 📝 CI/CD 与测试
11. 📝 性能优化与监控
12. 📝 产品化与持续迭代

本文由 Zyentor（智元界） 原创发布

本文发布于 Zyentor（智元界） —— AI 开发者社区