FastAPI+LlamaIndex

以下是一个结合FastAPI和LlamaIndex实现RAG（检索增强生成）功能的案例，将各个环节串一下，备查。

环境准备

系统环境

使用modelscope ，30个小时的免费使用，注册就行

https://www.modelscope.cn/my/mynotebook

Conda环境

AI开发中使用的各工具版本大多是0.X版本、技术迭代快、工具也相互依赖，开发中最让痛苦的就是平衡依赖的版本，让程序“当前”能正常运行。所以，需要隔离python环境就行 ，

安装软件

下载

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh

安装

bash Miniconda3-latest-Linux-x86_64.sh

激活

source ~/.bashrc

验证

conda --version

创建环境

创建

conda create -n myenv python=3.10

注意：python3.10是“目前”兼容性最好的版本，无特别的依赖要求就用该版本。

激活

conda activate myenv

注：后面的操作都是在myenv环境中操作

其他

pip install llama-index

pip install llama_index.vector_stores.chroma

RAG构建

从流程上梳理，一般AI项目的方案，数据>方案>模型>训练>评测>部署，这里只列出关键环节。

数据

重点，数据来源、数据结构、数据格式化问题，网络协议相关的数据集，准备好后，上传至服务器

模型

检索模型

检索模型一般选大一点，RAG检索需基于模型本身智能，所以模型要越大效果越好；

词嵌入模型

常用的一个https://www.modelscope.cn/models/BAAI/bge-small-zh-v1.5/summary

部署

总体

工具表

组件	技术	功能
后端	FastAPI	REST API、文档处理、RAG 核心逻辑
前端	Vue3 + Element Plus	用户界面、文档上传、问答交互
AI 框架	LlamaIndex	文档分块、向量化、检索增强生成
向量数据库	Chroma	文档向量存储与相似性搜索

结构图

服务	端口	服务名	功能说明
Nginx	80/443	gateway	API网关，入口代理、SSL、静态资源
Vue	80	frontend	前端静态资源 (Nginx托管)
FastAPI/LlamaIndex	8000	rag-api	处理用户请求和调用 RAG 流程
Chroma	8000	chroma	向量数据库服务

后端

环境准备：

使用框架

1. 使用FastAPI+LlamaIndex

FastAPI：https://fastapi.tiangolo.com/zh/

LlamaIndex：LlamaIndex - LlamaIndex

1. 安装依赖

pip install fastapi uvicorn llama-index python-dotenv pydantic sentence-transformers

目录结构：

编码app.py

功能设计

文件名：app.py

功能设计：

1. /query：处理自然语言查询
2. /health：提供健康检查
3. 返回结果包含：答案、来源文档片段

关键实现解析

1. 模型配置：
   • 使用BAAI/bge-small-zh-v1.5作为本地嵌入模型
   • 使用Qwen1___5-1___8B-Chat作为本地生成模型
   • 可通过修改常量切换为OpenAI等云服务
2. 索引构建：
   • 自动监控sample_docs目录变化
   • 支持多文档格式（PDF/TXT/MD等）
   • 使用HuggingFace模型进行本地向量化
3. API设计：
   • /query：处理自然语言查询
   • /health：提供健康检查
   • 返回结果包含：答案、来源文档片段
4. 错误处理：
   • 自动检测文档目录是否存在
   • 捕获模型加载和查询过程中的异常
   • 返回标准化的HTTP错误代码

功能编码

...详见资源链接...

启动服务

python main.py

两点说明

1. HuggingFace推理性能较差，需要使用vLLM进行推理
2. 数据存在内存，需要使用Chroma等进行持久化存储

前端：

简单使用vue构建一个测试页面，采用Vue 3 + Element Plus 的前端实现，与之前的 FastAPI RAG 服务完美配合。包含请求交互、加载状态和结果展示功能：

环境准备

创建项目

npm create vue@latest

安装依赖

npm install axios element-plus @element-plus/icons-vue

编写代码

功能设计

1. 交互体验优化
   • 支持回车键提交
   • 输入框即时清空
   • 加载状态提示（旋转图标 + 文字）
   • 错误消息醒目提示
2. 结果展示设计
   • 问题/答案分开展示
   • 参考文档折叠面板
   • 来源文档内容截取显示
   • 响应式布局（适配移动端）
3. 错误处理机制
   • 空输入校验
   • 网络错误捕获
   • 后端错误信息透传
   • 控制台错误日志打印
4. 此前端方案具备以下特点：
   • 与FastAPI RAG服务无缝对接
   • 完整的交互状态管理
   • 友好的错误提示系统
   • 响应式布局设计
   • 易于扩展的功能架构

功能编码

1. src/App.vue

服务端地址设置为：https://898800-proxy-8000.dsw-gateway-cn-hangzhou.data.aliyun.com/

1. src/main.js

启动服务

npm run dev

评测

前置环境

后端：

       本地地址：127.0.0.1:8000

       穿透地址：https://898800-proxy-8000.dsw-gateway-cn-hangzhou.data.aliyun.com/

前端：

       本次地址：127.0.0.1:5173

后端评测

在服务器端（aliyun.docker.Linux）

health接口-GET

curl -X GET "http://localhost:8000/health"

query接口-POST

curl -X POST "http://localhost:8000/query" -H "Content-Type: application/json" -d '{"question": "什么是路由？"}'

前端评测：

感觉良好的写好代码，但实际测试……都没成功，解决完各种问题后，发现：

跨域问题

浏览器的同源策略导致，正常需在服务器端进行配置，在FastAPI配置后，问题依旧；这里，本来就是是为了测试验证，最后选择让浏览器忽略同源方式，还不好用。

服务器问题

跨域问题解决后

- 通过浏览器：正常前端访问，仍旧被拦截，未能得到正确结果

- 使用Postman，问题依旧，得不到正确结果

问题原因

1. ModelScope 的代理网关可能覆盖了 FastAPI 的 CORS 响应头。
2. 网关默认配置不允许跨域，需通过 ModelScope 平台单独配置。

总结

本文尽量把RAG的各环节串联一起，尽量简单，部分功能，如：持久化、推理优化、文档分块等在实际落地时根据需要进行补充；还想再说的是数据集问题，嗯，特别重要!!!

项目地址：

https://github.com/iamleib/rag.fastindex

时间紧迫，部分内容不够严谨，多多理解！