AI 全栈开发实战（1）：产品定义与架构设计 —

前言

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

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

AI 全栈开发实战（1）：产品定义与架构设计 —— 做一个真正的 AI 知识库产品

前言