文档中心

云数据库 MySQL 版

最佳实践

基于 MySQL 使用 LangChain 框架搭建一个 RAG 应用

概述

本教程将一步步指导您如何利用 LangChain 框架，将火山引擎 RDS for MySQL 数据库作为向量存储，搭建一个完整的检索增强生成（RAG）应用。我们将使用火山引擎方舟（Ark）提供的 Embedding 和 LLM 模型，并通过 langchain-volcengine-mysql 这个集成库来简化操作。

读完本教程，您将掌握从环境准备、数据入库、向量检索到搭建完整问答（QA）链的全过程，并了解生产部署中的一些最佳实践。

整体架构

操作步骤

环境准备与依赖安装

在开始之前，请确保您已安装 Python 3.8 或更高版本。然后，我们需要安装所有必需的依赖库。这些库包括 LangChain 核心组件、火山引擎 Ark SDK 以及我们为 MySQL 打造的 LangChain 集成库。

打开您的终端，执行以下命令：

依赖库说明

langchain, langchain-core, langchain-classic: LangChain 的核心框架，提供了构建 RAG 应用的各种工具。

volcengine-python-sdk[ark]": 火山引擎方舟平台的官方 Python SDK，用于调用 Embedding 和 LLM 模型。

langchain-volcengine-mysql: 本次实战的核心，提供了将 RDS MySQL 用作 LangChain 向量存储和 Retriever 的能力。

pymysql: Python 连接 MySQL 数据库的驱动程序。

安全配置：设置环境变量

为了保障您的密钥和数据库凭证安全，强烈建议您使用环境变量来管理这些敏感信息，而不是将它们硬编码在代码中。这不仅更安全，也使得在不同环境（开发、测试、生产）中切换配置变得更加容易。

设置环境变量

请在您的开发环境中设置以下环境变量。您可以将它们添加到您的 .bashrc、.zshrc 文件中，或者在运行脚本前手动导出。

说明

ARK_API_KEY：请访问火山引擎方舟控制台获取。

MYSQL_*：这些是您 RDS for MySQL 实例的连接信息。

EMBEDDING_MODEL 和 LLM_MODEL：这些是您在方舟平台上部署的模型的 Endpoint ID。

在代码中读取环境变量

在 Python 脚本中，我们可以使用 os 模块来轻松读取这些环境变量。

初始化客户端与 Embeddings

接下来，我们需要初始化与火山引擎方舟服务的连接，并创建一个自定义的 Embedding 类来处理向量生成过程中的速率限制问题。

初始化 Ark 客户端

自定义 Embeddings 类

虽然 LangChain 提供了官方的火山引擎 Embedding 封装，但在实际调用中，我们可能会遇到因为请求频率过高而被限流的情况。为了让我们的应用更健壮，可以创建一个包装类，在其中加入自动重试和指数退避逻辑。

配置 MySQL 向量库

这是将 MySQL 融入 LangChain 生态的关键一步。langchain-volcengine-mysql 提供了一个非常便捷的 mysql.configure 函数，只需几行代码即可完成所有配置。

使用 mysql.configure

这个函数会根据您的配置，自动在数据库中创建或连接到指定的表，并准备好 vector_store 和 retriever 对象。

mysql.configure 参数详解

host, port, user, password, database: 标准的数据库连接参数。

table_name: 用于存储向量和文档的表名。如果该表不存在，库会自动创建。

embedding_function: LangChain 的 Embeddings 对象，用于将文本转换为向量。这里我们传入之前创建的 CustomArkEmbeddings 实例。

embedding_dim: Embedding 模型的输出维度。这是一个非常重要的参数，必须与您在 EMBEDDING_MODEL 中指定的模型维度完全匹配，否则会导致数据库错误。例如，bge-large-zh 模型的维度是 1024。

准备与写入文档数据

配置好向量库后，我们就可以向其中添加文档了。数据入库的过程主要包括：构造 Document 对象列表，然后调用 vector_store.add_documents 方法。

构造 Document 列表

每个 Document 对象包含 page_content（文档正文）和 metadata（元数据）两个部分。元数据对于后续的过滤和溯源非常有用。

添加入库并验证

调用 add_documents 方法，它会将文档内容转换为向量并与元数据一同存入 MySQL 表中。

搭建 RAG 问答链

现在，我们已经拥有了一个填充了知识的向量库。最后一步是将 retriever、LLM 和一个 PromptTemplate 组装成一个完整的 RAG 问答链。

初始化 LLM

首先，我们需要一个 LLM 来生成最终的答案。这里我们同样封装一个简单的 VolcengineLLM 类。

创建 Prompt 模板

一个好的 Prompt 模板能够指导 LLM 如何利用我们检索到的上下文来回答问题。

组装并测试 QA 链

LangChain 的 RetrievalQA 链能够非常方便地将所有组件整合在一起。

清理与生产注意事项

langchain-volcengine-mysql 提供了清理数据的方法，但在生产环境中需要谨慎使用。

按 ID 删除

如果您想删除特定的文档，可以使用 delete 方法并传入文档 ID 列表。

删除整张表

drop_table 方法会彻底删除存储向量的整张表。这是一个危险操作，请仅在测试和开发环境中使用。

生产环境最佳实践

逻辑删除：在生产环境中，通常建议使用逻辑删除（在元数据中添加一个 is_deleted 字段）而不是物理删除，以便于数据恢复和审计。

权限控制：确保您的数据库用户权限最小化，仅授予其执行 RAG 所需的 SELECT, INSERT, UPDATE, DELETE 权限，避免授予 DROP 或 CREATE 等高风险权限。

备份：定期备份您的数据库。

常见问题与排查

问题分类	可能原因与解决方案
连接失败	检查网络：确保您的应用服务器可以访问 RDS MySQL 实例的地址和端口。核对凭证：仔细检查 host, port, user, password, database 是否正确无误。白名单：检查 RDS MySQL 的 IP 白名单设置，是否已将应用服务器的 IP 加入。
权限或表不存在	权限不足：确认数据库用户是否具有对目标表的 SELECT, INSERT, UPDATE, DELETE 权限，以及在首次创建表时可能需要的 CREATE 权限。表名错误：检查 table_name 是否与数据库中实际的表名一致。
Embedding 维度不匹配	错误信息：通常会看到类似 Vector dimension mismatch 的数据库错误。解决方案：确认 mysql.configure 中的 embedding_dim 参数值与您使用的 Embedding 模型（EMBEDDING_MODEL）的实际输出维度完全一致。这是最常见的配置错误之一。
模型或 API Key 错误	无效的 Endpoint ID：确认 EMBEDDING_MODEL 和 LLM_MODEL 的值是正确的模型 Endpoint ID。无效的 API Key：确认 ARK_API_KEY 是有效的，并且有权限调用您指定的模型。
依赖版本冲突	检查环境：使用 pip freeze 检查当前环境中的库版本是否与要求兼容。创建虚拟环境：最佳实践是为每个项目创建一个独立的 Python 虚拟环境，以避免不同项目间的依赖冲突。

最近更新时间：2026.01.30 10:41:22

这个页面对您有帮助吗？

有用

无用