基于Azure SQL与Semantic Kernel的RAG应用实战：低成本实现向量搜索与智能问答

1. 项目概述当SQL数据库遇上向量搜索如果你正在用.NET技术栈构建智能应用并且数据已经躺在Azure SQL Database里那么“如何低成本、高效率地实现语义搜索和RAG检索增强生成”很可能就是你当前最头疼的问题。传统的全文搜索对同义词、上下文理解乏力而引入专门的向量数据库又意味着额外的架构复杂度、数据同步开销和学习成本。marcominerva/SqlDatabaseVectorSearch这个开源项目正是瞄准了这个痛点。它巧妙利用了Azure SQL Database原生支持的VECTOR数据类型让你能在熟悉的SQL环境和Entity Framework Core框架内直接进行向量相似度计算结合Azure OpenAI的嵌入模型和Semantic Kernel一站式搞定从文档解析、向量化存储到智能问答的完整流程。简单来说这个项目提供了一个基于Blazor Web App和Minimal API的样板应用。你可以通过Web界面轻松上传PDF、DOCX等文档它会自动切分文本、调用Azure OpenAI生成嵌入向量并存入SQL数据库。当用户提问时系统先从向量库中检索出最相关的文本片段再将这些片段作为上下文送给大模型生成精准、有据可查的答案。整个过程你的向量数据始终与业务数据共存于同一个SQL数据库中管理起来异常方便。对于已经深度依赖Azure和.NET生态的团队这无疑是一条实现AI能力快速落地的捷径。2. 核心架构与设计思路拆解2.1 为什么选择SQL Database作为向量存储在向量数据库百花齐放的今天选择将向量直接存入Azure SQL Database是一个需要权衡的架构决策。这个方案的核心优势在于“简化”和“统一”。许多企业应用的核心业务数据早已存储在关系型数据库中如果引入独立的向量数据库如Pinecone、Weaviate就需要建立复杂的数据管道来同步和维持一致性增加了运维负担和故障点。而Azure SQL Database的VECTOR类型允许你将向量作为表的常规列来处理可以直接使用SQL进行复杂的过滤、连接操作也能利用EF Core进行类型安全的编程。这对于希望快速验证概念、或对架构简洁性有极高要求的项目来说吸引力巨大。当然这个选择也有其明确的边界。项目文档中提到的VECTOR列最大维度为1998这直接限制了你能使用的嵌入模型。例如OpenAI的text-embedding-3-large模型虽然支持最高3072维但在此你必须通过其Dimensions参数将输出维度设置为1998或更低。此外大规模向量相似度搜索的性能与传统向量数据库的专用索引相比仍有差距。因此这个方案更适合数据量在百万级以下、对延迟要求不是极端苛刻、且强依赖SQL生态的中小型应用场景。2.2 Semantic Kernel的角色不只是胶水项目使用Microsoft的Semantic Kernel作为AI编排层这是一个非常务实的选择。Semantic Kernel的作用远不止是简单调用Azure OpenAI的API。它在这里承担了几个关键职责第一是插件化集成它封装了与Azure OpenAI的交互细节提供了统一的接口来处理聊天补全和嵌入生成第二是对话历史管理项目利用其能力实现了问题重述功能这对于多轮对话中保持上下文连贯至关重要第三是令牌计数通过与Microsoft.ML.Tokenizers集成它能精确计算每次请求的令牌消耗为成本监控和优化提供了基础。一个容易被忽略但至关重要的细节是配置文件中的ModelId字段。这里需要明确区分“部署名称”和“模型标识符”。你在Azure OpenAI Studio中创建的部署可以任意命名如my-gpt-4-deployment但appsettings.json里的ModelId必须填写模型本身的标准标识符如gpt-4o、text-embedding-3-small。因为Tokenizer库需要根据标准的模型ID来加载正确的分词器以确保令牌计数的准确性。如果这里填错令牌统计将完全失效你的成本核算就会出问题。2.3 数据流与核心组件解析整个应用的数据流清晰且模块化。TextChunkers目录下的文本分割工具是RAG效果的基石。它负责将上传的文档按语义和长度进行智能分块。分块策略块大小、重叠区直接影响检索质量块太大会引入无关噪声块太小则可能割裂完整语义。项目默认的实现是一个很好的起点但在实际生产中你可能需要根据文档类型技术手册、法律合同、客服对话调整这些参数。Data层定义了核心的EF Core实体和DbContext。其中Document、Chunk和Embedding实体之间的关系是理解存储模型的关键。一个文档Document包含多个文本块Chunk每个文本块对应一个嵌入向量Embedding。Embedding实体中的Vector属性被映射为SQL的VECTOR类型。当执行搜索时系统会计算问题向量的余弦相似度并返回最相关的几个文本块。Services层则封装了所有的业务逻辑包括文档处理、向量检索和问答生成使得Web App和Minimal API可以共享同一套核心服务。3. 从零开始的详细配置与部署实操3.1 环境准备与项目初始化首先你需要一个可用的Azure订阅。在Azure门户中创建两个资源一个是Azure SQL Database建议从基本层级开始以控制成本另一个是Azure OpenAI服务并在其中部署所需的模型通常至少需要一个聊天模型如GPT-4和一个嵌入模型如text-embedding-3-small。记下SQL数据库的连接字符串以及OpenAI服务的终结点和API密钥。接下来在本地开发环境克隆项目并完成基础配置git clone https://github.com/marcominerva/SqlDatabaseVectorSearch.git cd SqlDatabaseVectorSearch用你熟悉的IDE如Visual Studio 2022或Rider打开解决方案。找到SqlDatabaseVectorSearch/appsettings.json文件这是所有配置的核心。你需要修改ConnectionStrings:DefaultConnection为你的Azure SQL连接字符串。在AzureOpenAI部分填入终结点、API密钥以及你的模型部署名称。特别注意ModelId字段务必按照前文所述填写标准模型ID。3.2 数据库迁移与向量列配置配置完成后需要创建数据库结构。项目使用EF Core Code First已经包含了初始迁移文件。在包管理器控制台或终端中运行以下命令来应用迁移创建数据库和表dotnet ef database update --project SqlDatabaseVectorSearch这一步会创建包含VECTOR列的表。如果你想更改向量的维度例如使用text-embedding-3-large并指定1536维你需要修改两个地方一是ApplicationDbContext中modelBuilder.EntityEmbedding()的配置将.HasVectorDimensions(1536)二是找到初始迁移文件00000000000000_Initial.cs修改其中创建Vectors表的SQL语句将VECTOR(1536)。修改后需要生成新的迁移并更新数据库dotnet ef migrations add ChangeVectorDimensions --project SqlDatabaseVectorSearch dotnet ef database update --project SqlDatabaseVectorSearch注意直接修改已应用的初始迁移文件在生产环境中是危险操作可能导致数据丢失。更安全的做法是创建一个新的迁移来改变列定义。但对于初次搭建的测试环境直接修改初始迁移是最高效的。3.3 运行应用与初步验证完成配置后在项目根目录运行dotnet run --project SqlDatabaseVectorSearch/SqlDatabaseVectorSearch.csproj应用启动后控制台会输出监听的URL通常是https://localhost:5001。在浏览器中打开该地址你将看到Blazor Web App的界面。首先尝试上传一个小的TXT或PDF文档。上传成功后系统会异步处理文档分块、生成嵌入、存入数据库。你可以在界面中看到处理状态。处理完成后在搜索框输入一个与文档内容相关的问题测试语义搜索和RAG问答功能是否正常工作。同时你可以打开浏览器的开发者工具切换到网络Network标签页观察调用/api/ask或/api/ask-streaming的请求和响应直观感受流式和非流式返回的区别。4. 核心功能深度使用与API详解4.1 文档处理流程与文本分块策略上传文档是整个流程的起点。项目通过DocumentService来处理文件。它首先根据文件扩展名选择对应的解析器如PdfTextExtractor、DocxTextExtractor将文档内容提取为纯文本。接着文本被送入SemanticTextSplitter。这个分割器并非简单按字符数切割它会尝试在句子或自然段落边界处进行分割并保留一个小的重叠区Overlap以确保上下文信息不会在块与块之间完全丢失。例如一个段落如果刚好被切成两半重叠区可以保证后半部分的开头部分信息在前一个块中也有出现这能提高检索时召回相关内容的几率。你可以通过修改appsettings.json中的TextChunking配置节来调整分块行为TextChunking: { MaxChunkSize: 1024, ChunkOverlap: 128 }MaxChunkSize决定了每个文本块的最大令牌数注意是令牌数不是字符数。对于信息密度高的技术文档可以设置小一些如512对于文学性文本可以设置大一些如2048。ChunkOverlap是重叠的令牌数通常设置为块大小的10%-20%。调整这些参数后需要重新处理已上传的文档才能生效。4.2 向量搜索与相似度计算原理当用户提出一个问题时系统首先使用相同的嵌入模型将问题文本转换为一个向量。随后在SQL数据库中执行一个关键的向量相似度搜索。EF Core本身并不直接支持VECTOR类型的相似度运算因此项目使用了原始SQL查询。核心的查询片段如下SELECT TOP (count) c.*, e.* FROM Chunks c INNER JOIN Embeddings e ON c.Id e.ChunkId ORDER BY e.Vector.STDistance(questionEmbedding) ASC这里使用了STDistance函数来计算两个向量之间的欧几里得距离。距离越小表示向量在语义空间里越接近即内容越相似。你也可以使用DotProduct点积或Cosine余弦相似度函数这取决于你生成嵌入时使用的归一化方法。OpenAI的嵌入模型默认返回归一化后的向量模长为1此时余弦相似度与点积等价且计算效率高。项目选择欧氏距离是一种通用做法。检索出的最相关的几个文本块将与原始问题一起被构造为一个提示词Prompt发送给大模型生成最终答案。4.3 流式响应与非流式响应的选择与实践项目提供了/api/ask非流式和/api/ask-streaming流式两个端点适应不同场景。对于需要快速获取完整答案、并在后端进行后续处理的场景如自动归档、分析使用非流式接口更简单。其响应体一次包含所有信息原始问题、重述后的问题、完整答案、令牌使用详情和引用来源。而对于需要实时交互的Web应用流式接口/api/ask-streaming能极大提升用户体验。它基于Server-Sent Events (SSE) 或类似技术将答案拆分成一个个词元Token实时推送给前端。前端可以像打字机一样逐字显示答案用户无需等待全部生成完毕就能开始阅读。从前面文档的示例可以看出流式响应是一个JSON数组。第一个对象streamState: Start包含了问题、重述和初始令牌用量。随后是数十甚至数百个streamState: Append的对象每个只携带答案的一个小片段。最后一个对象streamState: End则包含了完整的令牌用量和引用列表。前端需要编写相应的逻辑来拼接这些片段并在收到结束信号后更新引用和令牌统计。5. 高级配置、优化与生产环境考量5.1 性能调优与索引策略随着向量数据量的增长全表扫描计算相似度会变得非常缓慢。虽然Azure SQL Database的VECTOR类型目前不支持像专用向量数据库那样的近似最近邻ANN索引如HNSW但你仍然可以通过一些策略优化性能。首先确保在Embeddings表上为ChunkId外键和DocumentId如果经常按文档过滤创建了索引。其次考虑对搜索进行“预过滤”。很多时候你的搜索是在特定文档集或特定时间段内进行的。你可以在SQL查询的WHERE子句中先加上这些业务过滤条件大幅缩小需要计算相似度的向量范围。另一个思路是采用混合搜索。将向量搜索与传统的关键字全文搜索SQL Server的CONTAINS或FREETEXT结合。例如先使用关键词快速筛选出可能相关的文档子集再在这个子集上做精确但昂贵的向量相似度计算。这需要在应用层实现逻辑但能有效平衡精度和速度。5.2 错误处理、监控与成本控制在生产环境中健壮性至关重要。你需要为以下几个关键点添加完善的错误处理和重试机制1)Azure OpenAI API调用可能会遇到速率限制、临时服务中断。使用Polly等库实现指数退避重试。2)文档解析用户可能上传损坏或格式不支持的文件需要在前端和后端都做好验证和友好提示。3)数据库操作处理好连接超时和死锁。监控方面除了应用本身的日志要重点关注两个指标令牌消耗和响应延迟。项目已经提供了详细的令牌使用信息你应该将这些数据收集到你的监控系统如Application Insights中并设置警报。例如如果单次问答的令牌数异常高可能意味着文档分块过大或提示词构造有问题。响应延迟则直接影响用户体验需要持续跟踪并优化。成本控制直接与令牌使用挂钩。除了监控还可以采取一些优化措施对于嵌入可以考虑缓存常见问题的嵌入向量避免重复计算对于聊天补全可以尝试调整提示词模板使其更简洁高效定期审查上传的文档清理过时或低价值的内容减少不必要的向量存储和检索开销。5.3 安全性与权限管理当前项目是一个演示应用在生产化时必须加强安全措施。首先API密钥管理绝对不要将API密钥硬编码在appsettings.json中并提交到代码仓库。使用Azure Key Vault或环境变量来管理敏感信息。在Azure App Service或Azure Container Apps中部署时可以直接使用其与Key Vault的集成。其次数据库连接安全使用Azure SQL Database的托管身份Managed Identity进行身份验证这比使用用户名密码的连接字符串更安全。确保数据库的防火墙规则仅允许来自你应用托管环境的IP地址访问。最后应用层授权当前的Minimal API和Blazor页面没有内置的认证授权机制。你需要集成Azure AD、Identity Server或其他认证方案确保只有授权用户才能上传文档和进行问答。特别是文档上传接口如果暴露在外网必须实施严格的权限控制和文件类型、大小检查防止恶意文件上传和DDoS攻击。6. 常见问题排查与实战技巧6.1 部署与连接问题问题应用启动时报错“无法连接到数据库”或“登录失败”。排查步骤检查appsettings.json中的连接字符串是否正确。确保服务器名称、数据库名称、用户名和密码无误。特别注意密码中的特殊字符是否需要转义。登录Azure门户检查Azure SQL Database的防火墙设置。确保“允许Azure服务和资源访问此服务器”已启用或者已将你本地开发机器的公网IP地址添加到防火墙规则中。如果使用托管身份请确保你的应用服务如Azure App Service已分配系统或用户分配的托管身份并且该身份在SQL数据库中被配置为包含用户CREATE USER [ ] FROM EXTERNAL PROVIDER并授予了必要的权限如db_owner。问题调用Azure OpenAI API时返回401或403错误。排查步骤确认appsettings.json中的Endpoint、Key、DeploymentName注意不是ModelId填写正确。终结点格式通常为https://your-resource-name.openai.azure.com/。在Azure门户中检查你的Azure OpenAI资源是否已成功部署了所需的模型如gpt-4、text-embedding-ada-002。部署名称是你创建部署时自定义的。检查API密钥是否已过期或被重置。可以在Azure门户中重新生成密钥。6.2 功能与数据处理问题问题上传文档后系统提示处理成功但搜索时返回“未找到相关内容”。排查步骤首先检查数据库。在SQL Server Management Studio或Azure Data Studio中查询Documents、Chunks、Embeddings表确认数据是否已成功写入。Embeddings表的Vector列应为非空。检查文档内容是否被正确解析。有时PDF解析器可能因为复杂的格式而提取出乱码或空白。尝试上传一个简单的纯文本.txt文件进行测试。检查文本分块是否过于激进。如果MaxChunkSize设置得太小可能导致语义碎片化检索时无法匹配到完整信息。尝试调大该值并重新处理文档。检查搜索问题是否与文档内容真正相关。尝试用文档中明确存在的句子或短语进行搜索。问题流式响应/api/ask-streaming在前端不显示或显示不完整。排查步骤使用Postman或curl直接调用API观察原始响应。流式响应应该是一系列由换行符分隔的JSON对象。确认后端是否正常输出。检查前端代码。Blazor的流式响应处理通常使用HttpClient并以HttpCompletionOption.ResponseHeadersRead模式读取响应流。确保前端正确解析了每个Append事件并将其内容累加到答案字符串中。检查网络。如果部署在互联网环境不稳定的网络可能导致流中断。查看浏览器开发者工具的网络面板确认SSE连接是否保持是否有错误。6.3 配置与调优技巧技巧优化提示词模板以提升答案质量。RAG的答案质量严重依赖提示词。项目中的提示词模板通常位于Services层的某个类中如ChatService。一个经典的RAG提示词结构如下你是一个专业的助手请根据以下上下文回答问题。 如果上下文不包含相关信息请直接回答“根据提供的资料我无法回答这个问题”。 上下文 {context} 问题{question}你可以根据你的领域知识优化这个模板。例如对于法律文档可以加入“请严格依据上下文不要进行推断”对于技术支持文档可以加入“请分步骤解答”。微调提示词是提升输出质量成本最低的方式。技巧处理超长文档和令牌限制。大模型的上下文窗口有限如GPT-4 Turbo是128K。当检索出的相关文本块总长度超过限制时需要做截断。项目默认会选取相似度最高的前N个块直到总令牌数接近上限。你可以在SearchService或相关逻辑中调整这个策略。更高级的策略可以包括对检索出的块进行二次精炼用大模型总结每个块或者采用“Map-Reduce”方法先让模型分别回答每个块的问题再综合所有答案。技巧为不同的文档类型使用不同的嵌入模型。虽然项目配置中通常指定一个嵌入模型但你可以扩展它。例如为纯文本使用text-embedding-3-small以节省成本和速度为代码片段使用专门针对代码训练的嵌入模型如OpenAI的text-embedding-3-large并指定更高维度。这需要在文档处理时根据文件类型或内容判断并动态选择不同的嵌入服务。这增加了复杂度但在混合型内容仓库中能显著提升搜索精度。