构建你自己的 ChatGPT：Azure OpenAI RAG Workshop 全解

想象这样一个场景：你是一家法律咨询公司的技术负责人，客户希望搭建一个私有知识库问答系统——员工可以用自然语言提问，系统基于公司积累的数千份合同、判例、法规文档，自动检索相关内容并生成回答。传统的 ChatGPT 无法做到，因为它只知道训练数据里的内容，无法接入你的私有知识库。

检索增强生成（Retrieval-Augmented Generation，RAG） 正是解决这一问题的核心技术。它的工作流程：文档向量化存入向量数据库 → 用户提问时检索最相关片段 → LLM 基于真实文档生成回答。这个模式解决了 LLM "幻觉"问题——答案有据可查。Azure OpenAI RAG Workshop 就是微软官方出品的完整 RAG 系统教学项目，不仅教你原理，更让你亲手跑通一个生产级的 ChatGPT 知识库问答系统。

项目背景与定位

Azure-Samples/azure-openai-rag-workshop 是微软 Azure 官方示例仓库，定位为 RAG 入门到实战的 Workshop（工作坊）。项目使用 azd-templates 标签，支持 Azure Developer CLI（azd）一键部署到 Azure 云环境——这对想要快速在生产环境验证 RAG 效果的企业开发者来说非常有价值。

主要 topics 覆盖了 RAG 系统的核心关键词：chatgpt、openai、langchain、rag、azure、nodejs、fastify。虽然主语言标记为 Bicep（IaC 工具），但实际业务代码以 TypeScript/Node.js 为主。

核心架构解析

项目采用 三服务分离架构，通过 docker-compose 编排：

图1：流式对话效果，实时逐 token 返回答案

1. Backend Service（端口 3000）

后端是整个系统的核心，采用 Fastify 框架构建 HTTP API。Fastify 是 Node.js 生态中性能最高的 Web 框架之一，相比 Express 有更高的吞吐量和更低的延迟——这对需要频繁调用 LLM API 的 RAG 系统尤为重要。

后端集成了完整的 LangChain.js 生态：

• @langchain/core + @langchain/openai：核心抽象层，底层对接 Azure OpenAI GPT-4/GPT-4o
• @langchain/community：社区扩展，支持多种向量存储后端
• @langchain/qdrant：Qdrant 向量数据库的 LangChain 集成

代码中使用 @dqbd/tiktoken 进行中文分词（tiktoken 是 OpenAI 开源的分词器，BPE 算法）。后端路由设计采用了 Fastify 的插件化架构：Fastify Autoload 自动加载 /routes 和 /plugins 目录下的模块，认证、CORS 等中间件以插件形式注入。

2. Ingestion Service（端口 3001）

文档摄取服务负责将外部数据导入向量数据库的管道：

1. 加载原始文档（支持多种格式）
2. 文本分块（chunking）：将长文档切分成适合 LLM 上下文窗口的小段落
3. 调用 Azure OpenAI Embedding API，将文本块转为向量
4. 将向量批量写入 Qdrant 向量数据库

摄取服务同样采用 Node.js + TypeScript + 多阶段 Dockerfile 构建，与后端保持一致的工程标准。

3. Frontend（Lit Web Components）

前端使用 Lit（Google 开发的 Web Components 框架）+ Vite 构建。Lit 是比 React 更轻量的选择——基于原生 Web Components 的模板系统，编译产物小、加载快、没有虚拟 DOM 开销，非常适合企业内部工具型应用。

前端通过 @microsoft/ai-chat-protocol 与后端通信，这是微软开源的 AI 对话协议库，定义了流式响应的标准格式。

图2：对话界面，支持 Markdown 渲染和代码高亮

4. Qdrant 向量数据库

项目选用 Qdrant 作为向量存储。Qdrant 是 Rust 实现的高性能向量数据库，支持混合检索、过滤条件、量化压缩。docker-compose 中通过 docker.io/qdrant/qdrant:v1.12.0 官方镜像启动，端口 6333，本地开发无需额外部署。

部署方式：三条路径

路径一：GitHub Codespaces（最简单，5分钟）

点击仓库页面的 "Open in GitHub Codespaces" 按钮，云端 VS Code 环境自动启动，所有依赖已预装，直接 docker-compose up 即可运行。零门槛，无需本地安装任何东西。

路径二：本地 Docker Compose（推荐，10-20分钟）

git clone https://github.com/Azure-Samples/azure-openai-rag-workshop.git
cd azure-openai-rag-workshop
cp .env.example .env
# 编辑 .env，填入 AZURE_OPENAI_API_ENDPOINT 等配置
docker-compose up

一条命令启动全部 3 个服务，自动构建 Node.js 镜像。前端 8000 端口，后端 API 3000 端口，Qdrant 6333 端口。

图3：Azure AI Search 检索结果展示

路径三：Azure Cloud（生产级，30分钟）

使用 azd CLI（Azure Developer CLI），一条命令将整个系统部署到 Azure 云：

azd up

infra/ 目录中的 Bicep 模板会自动创建 Azure App Service、Azure AI Search（可选替换 Qdrant）、Azure OpenAI 账户、Azure Cosmos DB（会话历史存储）等全套资源。

图4：GitHub Actions 自动化流水线，确保依赖包始终最新

技术栈全览

层次	技术选型	说明
前端 UI	Lit + Vite + TypeScript	轻量级 Web Components，性能优异
后端框架	Fastify 5 + TypeScript	极高吞吐量的 Node.js HTTP 框架
AI 框架	LangChain.js 0.3.x	模块化 LLM 应用开发框架
LLM	Azure OpenAI GPT-4/4o	企业级 GPT 服务
Embedding	text-embedding-3-small	1536 维向量，支持中文
向量数据库	Qdrant 1.12	Rust 实现，高性能
文档协议	@microsoft/ai-chat-protocol	微软开源 AI 对话协议
IaC	Bicep	Azure 资源定义
容器化	Docker + docker-compose	多阶段构建，镜像优化

文档与教学资源

项目配套了详尽的 Workshop 教程：

• docs/sections/：分步骤教程，涵盖从环境准备到生产部署的全流程
• docs/slides/：基于 remark.js 的演示文稿，适合教学或内部分享
• docs/assets/：大量截图和流程图，直观展示系统运行效果

项目还支持多种后端变体（Java Quarkus、AI Search 等），docs/sections 下有对应的专题指南。

图5：多轮对话支持，可追问和澄清

局限性与注意事项

1. 依赖 Azure OpenAI：整个系统的 LLM 能力依赖 Azure OpenAI 服务，需要有 Azure 账户和 OpenAI 配额，国内访问需要企业网络或特殊配置，按 token 计费。

2. Node.js 生态的 RAG 局限性：LangChain.js 0.3.x 已相当成熟，但某些高级功能（如复杂的混合检索策略）仍不如 Python 版本丰富。深度定制 RAG 逻辑可能需要迁移到 Python。

3. 数据安全：摄取服务会将文档内容发送给 Azure OpenAI，敏感商业数据需确保 Azure OpenAI 实例的合规配置（VNet 隔离等）。

4. 中文文档支持：项目原生支持中文分词（tiktoken），但主要文档和教程为英文，中文 RAG 场景需确认模型对中文的支持程度。

图6：RAG 架构示意

快速上手建议

1. 新手：从 GitHub Codespaces 开始，无需任何本地配置，先跑通对话流程
2. 进阶：本地 docker-compose 部署，研究后端代码，理解 RAG 检索和生成的完整链路
3. 生产：参考 infra/ 的 Bicep 模板，理解云原生架构，再按需调整