基于魔搭社区与阿里云百炼的云端 RAG 私有知识问答系统实现

0 序言

本文记录基于云端调用的 RAG 私有知识问答系统实现方案，区别于传统本地部署模式，该方案通过调用魔搭社区的 Embedding 模型 API 与阿里云百炼的大模型 API，避免了本地部署大模型带来的显存/算力压力（不过对于本文里的模型而言，实际上本地部署也电脑也跑得动，不过后续再用到一些很复杂的模型的话就比较建议通过云端调用的形式去学习，反正新用户的话会送很多免费部署的机会跟tokens，足够自己去使用了），同时保留私有文档的向量存储在本地的 Chroma 向量库中，兼顾灵活性与资源效率。

项目已完全跑通，核心流程优化为：上传私有 PDF 文档 → 文档拆分 → 调用魔搭云端 Embedding API 生成向量 → 存入本地 Chroma 向量库 → 用户提问 → 向量库检索相关文档 → 调用阿里云百炼大模型结合上下文生成回答，全程无需本地加载大模型文件，仅需配置云端 API 权限即可快速启动，我这里本地跟云端都部署过，云端的话确实流程会减少很多，有兴趣的读者可以两种方式都体验一下。

1 项目概述与核心信息

1.1 项目核心组件

• 当前状态：项目已完整跑通，可实现私有文档检索+云端大模型回答。
• 核心依赖：
  • 向量数据库：Chroma（本地存储，不需要将文档数据上传至云端）
  • Embedding 模型：魔搭社区 Qwen/Qwen3-Embedding-0.6B-GGUF（云端 API 调用/其他模型也可以）
  • 大模型：阿里云百炼 qwen-turbo（轻量免费模型，适合测试与日常问答）
  • 开发工具：VSCode + Python 3.12（本地开发环境，仅调用云端 API）
• 项目结构（对应我的本地目录）：

  LLM_testproj/          # 项目主目录
  ├─ chroma_db/          # 自动生成，存储文档向量数据
  ├─ .env                # 环境变量文件，存储云端 API 密钥
  ├─ document_processing.py  # 文档拆分+向量入库脚本
  ├─ qa_system.py        # 检索+云端大模型问答脚本
  └─ test_model1.py      # 魔搭 Embedding API 单独测试脚本
  

1.2 云端调用优势

相比本地部署，本方案的核心优势的在于：

• 资源轻量化：无需本地安装大模型文件，普通电脑即可开发。
• 维护成本低：云端模型由平台维护更新，无需手动处理模型量化、版本兼容问题。
• 扩展性强：可快速切换魔搭/阿里云的其他模型（如选择更优的 Embedding 模型、更强的大模型）。

2 环境准备

在启动云端调用前，需先配置本地开发环境与密钥管理，确保后续能安全、稳定地调用云端 API。

2.1 基础工具安装

• Python 环境：安装 Python 3.10+（推荐从 Python 官网 下载）。
• 开发工具：VSCode或PyCharm

2.2 虚拟环境配置（推荐）

虚拟环境可隔离项目依赖，避免与系统 Python 或其他项目冲突，操作步骤如下：

# 1. 进入项目主目录（如 D:\ProjectPython\LLM_testproj）
cd D:\ProjectPython\LLM_testproj  # 2. 创建名为 rag_env 的虚拟环境（依赖系统 Python 3.12）
D:\Python312\python.exe -m venv rag_env  # 3. 激活虚拟环境（不同系统命令不同）
# Windows PowerShell
.\rag_env\Scripts\Activate.ps1  
# Windows CMD
rag_env\Scripts\activate.bat  
# Mac/Linux
source rag_env/bin/activate  # 激活成功后，终端前缀会显示 (rag_env)

激活后，所有依赖安装与代码运行均在该环境中，退出虚拟环境可执行 deactivate 命令。

2.3 依赖包安装

项目需安装云端 API 调用、文档处理、向量库相关依赖，在激活的虚拟环境中执行：

pip install python-dotenv requests langchain-community langchain-chroma pypdf dashscope openai

• python-dotenv：加载 .env 文件中的密钥（避免硬编码泄露）。
• requests：发送 HTTP 请求调用魔搭 API。
• langchain-community/langchain-chroma：文档处理与 Chroma 向量库操作。
• pypdf：解析 PDF 文档。
• dashscope：阿里云百炼大模型的官方 SDK。
• openai：兼容魔搭 Embedding API 格式（用于测试脚本）。

选择好需要使用的模型，在终端上安装即可。

1. 安装魔搭工具：

pip install modelscope  # 激活虚拟环境后执行

2. 进入模型存储目录：

cd D:\ProjectPython\rag_private_qa\models  

3. 执行下载命令（参考模型页示例）：

modelscope download baichuan-inc/Baichuan2-7B-Chat --local_dir .  

这边建议在终端进行下载。

2.4 环境变量配置（关键）

云端 API 密钥属于敏感信息，需通过 .env 文件管理，步骤如下：

1. 在项目主目录（LLM_testproj）新建 .env 文件。
2. 按以下格式填写密钥（后续需替换为你的实际值）：

   # .env 文件内容
   MODELscope_API_URL=https:****.cn/v1
   MODELscope_API_KEY=ms-****
   DASHSCOPE_API_KEY=sk-****
   

3. 保存文件，后续代码会自动加载这些变量，无需在代码中硬编码。

3 云端资源配置

本项目依赖魔搭社区的 Embedding 模型与阿里云百炼的大模型，需先完成云端资源的权限配置，获取可调用的 API 地址与密钥。

这里两者之间的关系为：

环节	依赖组件	核心目标
文本→向量（检索基础）	魔搭 Embedding 模型	“理解” 语义相关性，找到相关文档
向量匹配（找相关内容）	Chroma 向量库（依赖 Embedding 结果）	快速定位私有文档中的关键信息
生成回答（整合信息）	阿里云百炼大模型	把碎片化内容整合成准确、流畅的回答

3.1 魔搭社区 Embedding 模型配置

魔搭社区提供 Qwen/Qwen3-Embedding-0.6B-GGUF 模型的 API 服务，需获取其 API 地址 与 访问令牌：

1. 访问 魔搭社区官网，注册并登录账号。
2. 搜索目标模型 Qwen/Qwen3-Embedding-0.6B-GGUF，进入模型详情页。
3. 在模型页的“API 调用”模块，复制 API 地址，粘贴到 .env 的 MODELscope_API_URL。
4. 生成访问令牌：
   • 点击右上角“个人中心”→“访问令牌”→“创建令牌”。
   • 输入令牌名称（如“RAG项目”），勾选“API 调用”权限，点击生成。
   • 复制生成的令牌（格式为 ms-xxxx），粘贴到 .env 的 MODELscope_API_KEY。

注意：令牌仅生成时可见，需立即保存，丢失后需要重新创建哦。
一般在网页里看到的会被你隐藏掉中间几位。

3.2 阿里云百炼大模型配置

阿里云百炼提供通义千问系列大模型，本项目使用免费轻量版 qwen-turbo，需获取 API 密钥：

1. 访问 阿里云百炼官网，注册并完成实名认证。
2. 进入“控制台”→“应用管理”→“创建应用”，输入应用名称。
3. 应用创建后，在API 密钥模块，复制 Access Key（格式为 sk-xxxx），粘贴到 .env 的 DASHSCOPE_API_KEY。
4. 确认模型可用性：在模型市场搜索 qwen-turbo，确认该模型已添加到你的应用中，一般来说，默认送的免费额度就已经足够测试了。

4 项目核心开发

本节按文档处理→向量入库→问答交互的流程，实现项目核心功能。

4.1 文档处理与向量入库（document_processing.py）

4.1.1 功能说明

将本地 PDF 文档拆分为片段，通过调用魔搭云端 Embedding API 生成向量，并将向量存入本地 Chroma 向量库，为后续检索做准备。

4.1.2 完整程序

import os
import json
import requests
from dotenv import load_dotenv  # 加载.env文件中的环境变量
from langchain_community.document_loaders import PyPDFLoader  # 加载PDF文档
from langchain.text_splitter import RecursiveCharacterTextSplitter  # 拆分文档
from langchain_chroma import Chroma  # 操作Chroma向量库
from langchain.embeddings.base import Embeddings  # 自定义Embedding必须继承的基类
from typing import List  # 类型提示，确保代码健壮性# -------------------------- 1. 加载环境变量--------------------------
# 从.env文件中读取魔搭API地址和密钥，避免硬编码泄露
load_dotenv()
MODEL_API_URL = os.getenv("MODELscope_API_URL")  # 从.env获取魔搭API地址
MODEL_API_KEY = os.getenv("MODELscope_API_KEY")  # 从.env获取魔搭访问令牌# -------------------------- 2. 自定义Embedding类（核心：对接魔搭云端API）--------------------------
class MyCustomEmbeddings(Embeddings)