做 .NET 项目想在应用里接 AI 能力很多人的第一反应是找各家的 SDK 往项目里塞。用一段时间就会发现模型服务商的 SDK 风格各不相同今天想从 A 厂商换到 B 厂商代码改动能把人劝退向量数据库同样五花八门接口更是各写各的。我最近在做一个内部知识库的语义搜索与问答 Demo核心就是围绕 Microsoft.Extensions.AI 和 Microsoft.Extensions.VectorData 这两个库展开把“模型调用”和“向量存储”这两块最容易绑死供应商的代码全部抽象化。这套组合搭好后换模型、换向量库都只是注册那一两行代码的事检索与问答的完整链路用几百行代码就能跑通。这篇文章不是堆概念而是把我从零搭一个“文档问答助手”的完整过程拆开来讲第一步搞清楚为什么是这两个库第二步把数据模型、服务注册这些容易踩坑的细节说透第三步逐步实现索引、检索、AI 回答的完整链路最后附上我实际遇到的坑和排查方法。无论你只是想做语义搜索还是想给应用加一个“资料库问答”能力都可以直接照搬这套结构。1. 整体设计思路为什么值得把“模型”和“向量库”都抽象出来1.1 模型调用的抽象能解决什么问题先说个场景。假设你的应用现在已经接好了某一家大模型把对话功能写完了。过了段时间你想试试另外一家因为推理更快、价格更低。这时候你面对的是两套完全不同的 SDK请求参数名不同、返回值包装不同、流式输出的写法不同、错误处理也不同项目里所有调用模型的地方都得跟着改一遍。在真正的工程里这种“绑定”会直接影响技术选型的灵活性和议价空间。Microsoft.Extensions.AI 做的事很简单把“调用大模型”这件事归纳成少数几个接口。最核心的是 IChatClient聊天补全和 IEmbeddingGenerator向量嵌入生成。你在业务代码里只依赖这两个接口具体背后是 OpenAI、本地 Ollama、Azure 还是其他服务商通过不同的实现包注入进去就行。这相当于给“大模型”装了一个通用插口就像我们平时用 USB 口接鼠标、键盘、硬盘一样设备的形状和规格不用你操心插上就能用。这个模式在 .NET 里其实很成熟我们对数据库编程时用的 ADO.NET、EF Core本质上就是这种抽象。模型供应商就是新的“数据库”AI 抽象层是新的“驱动管理器”。一旦想明白这个类比剩下的很多设计都顺理成章了。1.2 向量存储的抽象存储后端不绑架业务向量搜索的情况更“原始”。现在市面上的向量数据库或带向量能力的存储实在太多了有专门的向量数据库也有传统数据库新加的向量字段支持。每一个都有自己的 .NET 客户端API 风格天差地别。如果业务代码直接调用某个厂商的客户端等哪天因为性能、成本或运维原因想换一个后端整个数据访问层又得重写。Microsoft.Extensions.VectorData 解决的就是这一层它定义了 IVectorStore 这个总入口以及泛型的集合接口 IVectorStoreRecordCollectionTKey, TRecord。通过特性Attribute在实体类上标出哪个字段是主键、哪些是普通数据、哪个是向量字段然后用统一的 UpsertAsync、SearchAsync、DeleteAsync 来完成读写和相似度检索。不同后端有各自的实现包你面向接口编程后端实现只在注册时声明。有一点我要强调这个抽象的目标不是把每种后端的能力都塞进同一个接口。它踩的是最小公分母路线——主键读写、批量更新、按向量相似度检索、按筛选条件删除这些是所有后端都能做到的能力。你在这个抽象上写业务代码就不用担心被某个后端拖住。1.3 两个库合并起来一条完整的 RAG 链路现在把两块抽象拼起来就是标准的 RAG检索增强生成应用。一个典型的“知识库问答助手”可以拆成两条流程。第一条叫索引流程把文档读进来按策略切成片段对每个片段调用嵌入模型生成向量把“原文 向量 元数据”存进向量集合。第二条叫查询流程用户输入问题先把问题转成向量用这个向量去向量集合中做相似度搜索拿到若干个最相关的文档片段把它们作为上下文连同问题一起交给大模型让模型基于这些上下文生成回答。整个链路里Microsoft.Extensions.AI 管嵌入和聊天Microsoft.Extensions.VectorData 管存取和检索。业务代码里几乎看不到任何“某厂商专用”的类型。你写的是“给文本生成向量”“把向量存进去”“按向量搜出来”“让模型回答”而不是“调用 XX API 如何如何”。这就是抽象的价值。2. 动手之前要搞清的细节包、模型、接口2.1 包结构与其他依赖两个库目前都在预览阶段所以在项目里引入时建议锁定版本。为了把 Demo 跑起来一般需要四类包核心抽象包提供 IChatClient、IEmbeddingGenerator、IVectorStore 这些接口定义模型实现包例如面向 OpenAI 的、面向 Azure AI Inference 的、面向本地 Ollama 的选其中一个或几个向量存储实现包例如内存实现、Redis、Qdrant、Azure AI Search 等任选宿主支持包用来做依赖注入和配置通常在你用 Host.CreateApplicationBuilder 时会用到。如果你不想引入外部依赖直接用内存向量存储实现就能跑通全流程。这一点对我的价值很大早期做原型时不用着急部署任何中间件用内存存储先验证模型和 Prompt等逻辑稳定了再切到生产级存储后端。2.2 数据模型用特性明确字段职责在 VectorData 的词库里一条存储记录由三部分组成Key、Data、Vector。Key 可以是 Guid、long、string 等类型用于唯一标识记录。Data 是普通的业务字段比如文档原文、来源文件名、创建时间。Vector 是嵌入生成的浮点数组。具体写法是定义一个类然后给每个属性打上对应的特性internal sealed class DocumentChunk { [VectorStoreRecordKey] public Guid Id { get; set; } [VectorStoreRecordData] public string Content { get; set; } [VectorStoreRecordData] public string Source { get; set; } [VectorStoreRecordVector(Dimensions: 768, DistanceFunction.CosineSimilarity)] public ReadOnlyMemoryfloat Vector { get; set; } }这里有个容易忽略的点Dimensions 必须和你使用的嵌入模型输出的维度一致。比如 nomic-embed-text 的维度是 768all-minilm 的维度是 384。如果你用错维度某些存储实现可能不会当场报错但检索结果会完全不对而在强 schema 的后端里维度不一致直接建集合都会失败。所以我在项目里习惯把“模型 向量维度”写成一个常量绑定在同一个地方避免两头维护。距离函数的选择也有门道。常用三种CosineSimilarity 适合文本语义场景因为它在一定程度上不受向量长度影响EuclideanDistance 在图像特征、坐标类数据里更常见ManhattanDistance 则更少用。文本向量搜索默认选余弦相似度基本不会错。2.3 核心接口与生命周期这个方案的代码体验主要围绕三个接口展开。IChatClient 代表一个“能对话的模型”。它有 GetResponseAsync / GetStreamingResponseAsync 等方法输入的是一批 ChatMessage输出的是 ChatResponse。你可以在上面设置温度、MaxTokens 等参数。IEmbeddingGeneratorTInput, TEmbedding 代表一个能把输入转成向量的模型。TInput 通常是 stringTEmbedding 通常是 Embedding 。调用一次 GenerateEmbeddingAsync拿到的结果里就是 float 数组。IVectorStore 是向量存储的总入口。通过 GetCollection 拿到具体某个集合再对集合做建表、插入、检索。在 DI 容器里这些对象默认是单例还是每次创建取决于实现包的注册方式。我的建议是嵌入生成器和聊天客户端按单例注册因为它们内部通常有连接池或缓存反复创建既浪费又容易把连接打满集合对象可以是作用域或每次获取因为很多存储实现里它只是个轻量句柄。具体到某个实现包文档里一般都会写明但我实测下来的规律是注册为 Singleton 最稳妥性能也最好。3. 实操全流程从空白项目到能用的语义搜索问答3.1 环境准备我这次用的是本地 Ollama理由很简单零 API Key、零网络请求、模型权重本地跑适合先把整条链路调通也没有成本压力。启动 Ollama 之后拉两个模型nomic-embed-text专门做嵌入的模型768 维本地跑起来很快检索效果在同体积下算不错的。qwen2.5:7b 或者 llama3.1:8b作为聊天模型用于最后生成回答7B 档位在消费级笔记本上已经能给出比较能看的答案。项目侧只需要一个 .NET 8 SDK 的空项目不需要数据库。内存向量存储已经够跑通 Demo。3.2 创建项目并注册服务新建一个控制台项目后把上面说的几类包装进去。这里我提醒一句预览版的包一定把版本号锁住团队里其他人拉代码才不会因为自动解析到不同版本而到处报错。Program.cs 里的注册代码using Microsoft.Extensions.AI; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Hosting; using Microsoft.Extensions.VectorData; var builder Host.CreateApplicationBuilder(args); var ollamaEndpoint new Uri(http://localhost:11434); builder.Services.AddOllamaEmbeddingGenerator(ollamaEndpoint, nomic-embed-text); builder.Services.AddOllamaChatClient(ollamaEndpoint, qwen2.5:7b); builder.Services.AddSingletonIVectorStore(new InMemoryVectorStore()); var app builder.Build(); var embeddingGenerator app.Services.GetRequiredServiceIEmbeddingGeneratorstring, Embeddingfloat(); var chatClient app.Services.GetRequiredServiceIChatClient(); var vectorStore app.Services.GetRequiredServiceIVectorStore();看完这段代码你应该能感受到前面说的“注册即切换”。如果后面想把 Ollama 换成 OpenAI 的接口只需要把 AddOllamaEmbeddingGenerator 和 AddOllamaChatClient 换成对应的实现包扩展方法其余的业务代码一行不动。同理把 InMemoryVectorStore 换成 Redis 或 Qdrant 实现也只发生在注册这一小段。3.3 文档分块、生成嵌入、写索引分块策略是 RAG 里最容易被低估的一环。分太大一个片段包含太多无关信息检索召回的片段里有效信息被稀释回答容易跑偏分太小单个上下文缺乏完整语义模型拼起来也费劲。我常用的默认是 500 个字符一块、重叠 50 个字符。重叠的意义是把上一个块末尾的语义尾巴保留到下一个块开头避免关键句子正好被切断。分块的实现可以先用一个最简单的按固定长度滑动窗口static IEnumerablestring SplitIntoChunks(string text, int chunkSize 500, int overlap 50) { var normalized System.Text.RegularExpressions.Regex.Replace(text, \s, ).Trim(); if (string.IsNullOrEmpty(normalized)) yield break; var start 0; while (start normalized.Length) { var length Math.Min(chunkSize, normalized.Length - start); yield return normalized.Substring(start, length); if (start length normalized.Length) yield break; start Math.Max(1, length - overlap); } }之后对每个片段做嵌入、写入集合var collection vectorStore.GetCollectionGuid, DocumentChunk(docs); await collection.CreateCollectionIfNotExistsAsync(); var longText File.ReadAllText(sample-doc.txt); var index 0; foreach (var chunkText in SplitIntoChunks(longText)) { var embedding await embeddingGenerator.GenerateEmbeddingAsync(chunkText); await collection.UpsertAsync(new DocumentChunk { Id Guid.NewGuid(), Content chunkText, Source sample-doc.txt, Vector embedding.Vector }); index; if (index % 20 0) Console.WriteLine($已索引 {index} 个分块); }这里有两个实践细节一是 CreateCollectionIfNotExistsAsync 确保集合存在重复跑不会炸二是 UpsertAsync 是“不存在就插入、存在就更新”的语义重跑某个文档的索引不必先手动删掉旧数据。这种幂等性在真实场景里很重要因为文档会经常更新我们不可能每次全量重建。3.4 查询把问题变成向量搜出相关片段查询流程写起来非常对称。先给用户问题生成向量再用向量搜索集合var query 今年公司的年度重点目标有哪些; var queryEmbedding await embeddingGenerator.GenerateEmbeddingAsync(query); var searchOptions new VectorSearchOptions { Top 3, VectorProperty r r.Vector }; var searchResults new ListVectorSearchResultDocumentChunk(); await foreach (var result in collection.SearchAsync(queryEmbedding.Vector, searchOptions)) { searchResults.Add(result); Console.WriteLine($得分 {result.Score:F4}: {result.Record.Content[..Math.Min(80, result.Record.Content.Length)]}); }Top 通常取 3 到 5 之间太少容易漏太多会把不相关的内容塞进上下文拖慢回答速度并稀释注意力。这里我把 Top 设为 3是为了让回答内容更聚焦。还有一个点容易被忽略如果你想按 Source 或日期做过滤VectorSearchOptions 里有 Filter 选项。在真实系统里比如“只从 2025 年的文档中检索”没有过滤器就得先搜出来再在内存里筛低效且结果数可能不够。3.5 让大模型基于检索结果生成回答最后一步是把检索结果拼接成 Prompt交给 IChatClient。我习惯在 Prompt 里把角色、任务边界、资料区、问题区明确分隔开并且加一句“资料里没有就直说没有”这是为了减少模型凭空编造的风险也是 RAG 应用里最基础的 Prompt 工程。示例代码var context string.Join(\n\n---\n\n, searchResults.Select(r r.Record.Content)); var prompt $ 你是知识库问答助手。请只根据下面给出的资料回答问题。 如果资料里没有足够信息请直接说“根据现有资料无法回答”不要猜测。 资料 {context} 用户问题{query} 回答 ; var response await chatClient.GetResponseAsync(prompt); Console.WriteLine(); Console.WriteLine( 回答 ); Console.WriteLine(response.Text);跑完上面的几步一个本地、完全可控、免费的知识库问答助手就出来了。整个涉及 AI 和向量检索的业务代码加起来不超过两百行。后面如果要把它变成 Web API把这段逻辑挪到服务层加上 Http 接口就可以。3.6 生产化内存存储换成真实后端很多人会问内存向量库 Demo 跑通了生产环境怎么办我的回答是先想清楚你的数据规模和 SLA 需求再决定。如果数据量只有几千条单机内存存储配合持久化方案就够了。如果数据在百万级、需要集群、需要高可用或者你想直接使用已有的云服务比如 Redis、Qdrant、Azure AI Search 等就把注册代码中的 InMemoryVectorStore 换成对应的实现。业务代码基本上不用动因为集合接口的语义是一样的。当然不同实现支持的能力会有差异例如某些后端原生支持全文过滤、父子文档切分、混合检索这些高级能力可能逃逸到厂商特有的 API 上。我的建议是先用抽象接口写主流程等真的需要某个高级能力时再有针对性地去查具体实现的文档这比一开始就深绑某个后端要稳得多。4. 实践中最容易踩的坑以及对应的排查手段4.1 预览版的版本与 API 一致性第一个坑是 NuGet 包之间的版本错配。微软这套扩展库目前还在预览阶段抽象包和实现包一起升级是常态。有时候抽象包升到新预览版某个实现包还停在旧版本两者之间的接口签名大概率对不上最常见的表现就是“编译不过找不到某某方法”。我的做法是版本号统一用同一个来源。要么全部选最新要么全部锁定在某一组经过验证的组合上项目文件里用中央包管理把版本统一管理起来。千万不要让 IDE 里的“自动更新”随意把抽象包升到别的版本。每次升级后第一件事是先编译整个解决方案再跑一遍检索 Demo确认行为没变化。4.2 检索结果为空或得分异常我调试过程中遇到最多的现象是查询向量搜不出结果或者搜出的结果得分接近 0但明明库里就有相关内容。排查方向按顺序走第一步检查集合是否真的写了数据。拿内存存储来说直接枚举集合里所有记录看看数量是否匹配。第二步检查向量维度是否匹配。如果你换了嵌入模型但数据模型里的 Dimensions 没有同步改某些存储会把所有向量当垃圾处理。第三步检查距离函数。如果后端要求余弦相似度但你用的是欧氏距离得分和排序逻辑都会变。第四步检查查询向量生成有没有失败比如 Ollama 服务没起来嵌入调用会静默超时或抛异常你以为查不到数据其实是向量压根没生成。4.3 批量写入的性能经验如果你要索引的是几千个分块逐条生成嵌入再逐条 Upsert会发现整个索引用了几分钟甚至更久。这不是库的问题而是调用方式的问题。优化思路有三个第一批量生成嵌入。很多实现包支持传入一组输入一起返回一组向量这样比单条循环少了很多进程切换开销。第二批量 Upsert。向量集合的 Upsert 通常也提供批量重载尽量凑一批再写。第三控制并发。可以用简单的 Parallel.ForEachAsync 把索引过程并行化但注意别把 Ollama 或远端嵌入服务的线程池打满。我在本地机器上把并发度限制在 4 左右整体索引时间能缩减一半以上。4.4 调试完怎么验证整条链路最后分享一个调试技巧把每一步都落到控制台或日志里。很多人一跑就只关心最后的回答一旦回答错了根本分不清是检索错了还是模型答错了。我会在查询阶段把 Top 3 的文本和 Score 全部打出来看一眼。如果检索出来的内容本身就不对那就别浪费时间去调 Prompt只有检索内容是对的、回答还不对才去调 Prompt 或换聊天模型。这套“先验证检索再验证生成”的二分法能帮你把排查范围缩小很多。实际开发里把 Score 阈值也加进去比如低于某个分数的片段直接丢弃能进一步减少无关上下文对回答的干扰。4.5 常见问题速查表我自己在项目里列过一张速查表遇到问题先看症状再按行定位能省不少时间症状优先排查方向解决思路编译报错方法找不到各包版本是否一致锁定同一组版本升级后先编译再跑检索结果为空集合是否有数据、向量维度是否匹配枚举集合记录确认数据量核对 Dimensions得分接近 0 且排序乱距离函数是否正确改为 CosineSimilarity并检查查询向量生成索引特别慢是否单条嵌入 单条写入批量生成嵌入、批量 Upsert、限制并发数回答内容与检索内容无关Prompt 结构或上下文质量检查 Top K 和 Score 阈值减少无关片段以上这些坑基本都是我自己实际踩过一遍才总结出来的。API 名称、包版本这些随着预览版迭代可能会变但“先确认检索对了再检查生成”这个排错思路长期有效。最后再补一句个人体会。这套组合给我的最大感受是“克制”抽象层只定义最基本的能力没有试图包办所有 AI 功能。你在上面写的业务代码哪天想换底层实现都只动注册那几行。做 AI 应用原型时我现在基本都用这套起手先内存跑通再按需升级后端。也建议你从一个小场景开始比如把你手头最常用的一份文档做成可问答的知识库跑一遍这套流程对整套机制的体感会远比读十篇文章来得深。