简介基于微软Semantic Kernel和.NET 8构建的FastWiki知识库系统完整设计源码面向需要搭建智能知识检索平台的.NET开发者及希望掌握语义内核落地技巧的架构师。项目以后端框架MasaFramework和前端框架React为双核心专注于深度学习与自然语言处理场景旨在提供高效、易用且可扩展的智能向量搜索方案帮助团队快速实现知识库的语义化检索与问答。整个zip压缩包共包含917个文件包体仅3.37MB其中386个TypeScript源文件与265个TSX模板文件用于构建前端界面172个C#源文件承载后端业务逻辑、数据库上下文和迁移版本61个JSON配置文件管理依赖与运行参数另含csproj项目文件、Dockerfile容器化配置和gitmodules子模块引用目录划分清晰便于按层次阅读。已有232人学习下载。研读源码可以完整掌握基于语义内核的知识库设计思路包括向量化分块、嵌入生成、相似度检索、问答提示词编排等核心流程同时看到从数据库初始化到字段调整的开发细节适合企业级知识库系统的二次开发与功能扩展。1. Semantic Kernel 和 FastWiki 知识库系统为什么要在 .NET 8 里做语义问答很多团队其实已经有“知识库”了一堆 Markdown 文档、企业 wiki、PDF 制度文件搜索靠数据库LIKE或者 Elasticsearch 分词。问题是用户问“今年报销流程有没有变”关键词搜出来的是去年的旧政策用户要的是“哪一条规则能回答我的问题”不是“哪些文件包含报销两个字”。FastWiki 这种项目的价值是把 Microsoft Semantic Kernel 当作编排层在 .NET 8 进程内完成从文档加载、向量化、语义检索到生成回答的完整链路。它适合两种人一种是给内部做知识库但不想把文档内容直接交给外部问答服务的团队另一种是已经用 C# 技术栈、想通过源码设计把握 RAG 数据流而不是只调 API 的开发。这个系统的核心矛盾不在大模型本身而在切片是否准、召回是否对、提示词有没有让模型知道什么时候该闭嘴。2. .NET 8 项目拆分与 Semantic Kernel 的最小运行链路2.1 从源码模块看 FastWiki 类项目的引用方向Core、Infrastructure、Web我读一个 .NET 源码项目时不会先按文件名找实现而是先看.csproj里的ProjectReference方向。FastWiki 这类知识库系统通常拆成四层Core只放实体、接口和领域规则Infrastructure负责向量库、文件存储、PDF 解析这些可替换实现Service编排导入、检索和问答用例Web只暴露 HTTP API 和后台任务。这样拆不是为了分层而分层而是因为知识库系统功能面太杂导入、解析、切分、向量化、召回、对话、权限、审计每一步都可能换实现比如从 Qdrant 换到 Azure AI Search不能牵连对话编排代码。刚上手时容易掉进“源码在哪个工程”的迷宫这和读大型 C 项目要从构建脚本切入一样。在 .NET 8 里最直接的入口是找DependencyInjection扩展方法比如AddWikiCore()、AddInfrastructure()它们决定接口与实现的绑定关系。以 FastWiki 的设计思路看Kernel对象不会在 Web 层直接new出来而是由基础设施层注册成单例并通过一个端口接口暴露给用例层。这样做的收益很实际单元测试时可以把向量库换成VolatileMemoryStore把嵌入模型换成固定向量跑完一轮切分和检索用例。2.2 Kernel.CreateBuilder 最小链路模型、API Key、执行一次回答先跑通最小链路再谈优化。下面代码是 .NET 8 控制台项目里最小可运行的 Semantic Kernel 调用目标是把“提示词渲染 → 模型生成 → 输出结果”这条链路在本地立起来。using Microsoft.SemanticKernel; const string modelId gpt-4o-mini; const string apiKey your-api-key; var kernel Kernel.CreateBuilder() .AddOpenAITextGeneration(modelId, apiKey) .Build(); var result await kernel.InvokePromptAsync(用一句话解释知识库分块的作用); Console.WriteLine(result);Kernel.CreateBuilder()是 Semantic Kernel 1.x 的构建入口效果类似于 ASP.NET Core 的WebApplication.CreateBuilder。AddOpenAITextGeneration注册的是“文本生成服务”负责把渲染后的提示词发给模型。这里modelId和apiKey只是形参实际开发中必须从IConfiguration和用户机密里读取不能写死在源码里。但知识库系统只注册文本生成不够后面向量化还需要嵌入模型。常见做法是同时注册两个服务var kernel Kernel.CreateBuilder() .AddOpenAITextGeneration(modelId: gpt-4o-mini, apiKey: apiKey) .AddOpenAITextEmbeddingGeneration(modelId: text-embedding-3-small, apiKey: apiKey) .Build();AddOpenAITextEmbeddingGeneration注册的是嵌入生成服务输入一段文本输出一个浮点数组也就是向量。这里提醒一个容易混淆的配置项文本生成模型和嵌入模型通常是两个不同型号很多团队误以为只配一个 GPT 模型就能做语义检索结果在向量化阶段反复报维度错误。在 FastWiki 类项目的源码里这两个服务注册位置不会放在同一个方法里因为文本生成模型可能被替换成本地模型而嵌入模型可能因成本原因换成开源模型需要独立开关。2.3 Kernel 的函数标注为什么要给模型“说明书”Semantic Kernel 和普通 HTTP 调 OpenAI 最大的区别是它可以管理“函数”。函数分三类提示词函数、原生函数、插件。知识库系统最核心的是原生函数也就是用 C# 方法完成向量检索再让模型决定是否调用它。为了让模型正确调用方法上必须写清函数名和描述。using Microsoft.SemanticKernel; public sealed class WikiStatusPlugin { [KernelFunction(get_knowledge_base_status)] [Description(返回知识库中最近一次索引完成的时间和文档数量)] public string GetStatus() { return 最近索引时间2025-01-15 08:30文档数量128; } }[KernelFunction]参数决定模型看到的函数名[Description]是给模型看的功能说明书。模型不是通过编译期强类型知道该调用谁而是根据描述文本判断。描述写得越具体调用准确率越高。比如把“返回知识库状态”改成“返回知识库中最近一次索引完成的时间和文档数量”模型在用户问“索引更新了吗”时就更容易命中这个函数。这里的wiki前缀只是属性参数不参与目录结构。后续章节中我会把真正的向量检索函数留给 RAG 链路使用这里先说明函数注册与模型调度的边界。模型可见名称说明对象典型失败点[KernelFunction]函数名决定模型在 JSON 调用中填什么用中文名可能导致模型生成非法标识符[Description]函数行为说明描述太短模型在多个函数间选择错误[Parameter]上的描述参数含义与格式参数含义不清模型传错字符串注册插件使用kernel.Plugins.AddFromTypeWikiStatusPlugin()之后模型会在判断需要该能力时自动调用。需要注意的是这种调用不是每次必发生模型可能直接回答也可能调用多个函数。后面的 RAG 链路本质上是把“检索”这个动作也变成函数并和提示词模板串在一起。理解了这条边界再去看 FastWiki 的源码你看到的就不是一个个散落的类而是一张“函数注册表 提示词模板 向量库”的关系网。3. 知识库核心文档解析、切片与向量化存储3.1 文档解析的输入输出约定统一成纯文本FastWiki 这类系统的输入文件五花八门最常见的是 PDF、Word、Markdown、TXT。如果每个业务方法都直接处理文件流代码会被各种解析库的using淹没。我一般会先定一个统一接口所有解析器都输出纯文本并且保留段落顺序和必要的标题层级。public interface ITextExtractor { string Extract(Stream fileStream, string fileName); }Extract接收文件流和文件名文件名用于判断解析类型。PDF 可以用 PdfPig 或 PdfPlex 这类库处理但要注意 PDF 经常没有可靠的文字层扫描件必须走 OCR这是一条完全不同的管线。Word 可以用 Open XML SDKMarkdown 和 TXT 直接读字符流后做编码转换。接口的价值在于下游分块器只认字符串不关心文件是从哪个格式来的。解析完成后建议顺手记录两个元数据来源文件名和页面或章节号。这样后续回答可以溯源到具体文档用户不会接受“AI 说应该这样做”却看不到出处。在源码设计里元数据会随着文本切片一起写入向量库形成一条从回答到原文档的引用链。3.2 分块Chunking策略固定窗口与重叠参数的取舍这是整个知识库工程里最容易被低估的环节。模型一次能接收的上下文有限向量检索的召回粒度也决定了回答质量。我见过的错误做法是把整个章节塞进一个向量结果一个切片几千字检索时相关片段被无关内容稀释生成阶段又截断。常用的兜底方案是固定字符窗口加重叠。以下代码按最大字符数切分并让相邻切片保留一段重叠文字public static Liststring SplitText(string text, int maxChars, int overlapChars) { var chunks new Liststring(); var start 0; while (start text.Length) { var length Math.Min(maxChars, text.Length - start); var chunk text.Substring(start, length); if (!string.IsNullOrWhiteSpace(chunk)) { chunks.Add(chunk); } if (start length text.Length) { break; } start length - overlapChars; } return chunks; }参数maxChars控制每个向量的内容长度。知识库场景里500 到 800 字符的切片比 2000 字符切片更容易命中精确答案。overlapChars让相邻切片共用几十个字符避免一个问题中涉及的关键描述恰好被截断成两半。这里给出一组常用起始参数具体还是要按你的文档语言和句式习惯调。参数推荐起点增大效果减小效果maxChars600上下文更完整但向量噪声增加精确率上升但检索片段过于碎片overlapChars80降低截断风险节省向量存储空间minRelevanceScore0.70回答更谨慎漏召回回答容易说“找不到”固定窗口只是兜底。如果原始文档是 Markdown 或带标题的结构化内容最好先按一级标题切一次再用固定窗口处理过长的段落。FastWiki 类项目源码中值得读的部分往往不是解析库的封装而是这个“标题切分 长度重叠”的组合函数它决定了后面每一步的上限。3.3 向量化与存储从 VolatileMemoryStore 到生产向量库分块完成后每一段文本都要交给嵌入模型生成向量再写入向量存储。语义检索不依赖关键词完全一致而是比较向量距离所以“报销流程”和“费用申请流程”也能被关联起来。先看一个不依赖外部数据库的最小实现非常适合本地调试和自动化测试using Microsoft.SemanticKernel.Connectors.OpenAI; using Microsoft.SemanticKernel.Memory; using Microsoft.SemanticKernel; const string apiKey your-api-key; var embeddingGenerator new OpenAITextEmbeddingGeneration( modelId: text-embedding-3-small, apiKey: apiKey); var memoryStore new VolatileMemoryStore(); var memory new SemanticTextMemory(memoryStore, embeddingGenerator); await memory.SaveInformationAsync( collection: wiki, text: 报销单需要部门主管签字后才能提交财务。, id: policy-001, description: 报销制度-签字流程); var results await memory.SearchAsync( collection: wiki, query: 报销找谁签字, limit: 3, minRelevanceScore: 0.70); foreach (var item in results) { Console.WriteLine(${item.Metadata.Text} | 相关度 {item.RelevanceScore:P0}); }collection是命名空间相当于数据库里的表id必须唯一description是供检索和展示使用的辅助文本。SearchAsync的query是用户原话limit控制返回条数minRelevanceScore是召回质量门槛。如果阈值设得太低垃圾片段会进入提示词回答容易胡编设得太高又可能召回为空模型只能回答“不知道”。VolatileMemoryStore把向量存在内存里进程一重启就清空所以它只适合验证链路。生产环境需要把VolatileMemoryStore换成正经向量库。Semantic Kernel 1.x 的IMemoryStore提供统一接口常见选择有 Qdrant、Azure AI Search、PostgreSQL pgvector。选型时看三个纬度选型维度检查项部署方式能否在既有内网环境部署是否强制走外部 SaaS向量维度嵌入模型的输出维度是否在向量库支持范围内过滤能力是否支持按权限、部门、文档来源做混合过滤很多团队在本地调试时用内存库跑通上线前才接入 Qdrant这是最稳的路径。注意不同版本下连接器类名会有迁移源码阅读时不要死记QdrantMemoryStore还是QdrantVectorStore重点看IMemoryStore的实现类注册在哪个模块。只要能满足SaveInformationAsync和SearchAsync两个操作上层代码就不需要大改。4. 检索问答Semantic Kernel 的 RAG 调用链与提示词设计4.1 召回链路从问题到上下文的两次“翻译”知识库问答不是简单地把用户问题塞给模型。完整链路是先把原始问题转成一个适合向量检索的表达再从向量库召回最相关的切片最后把切片作为上下文连同用户问题一起交给生成模型。第二步与第三步之间还有一个容易被忽略的环节阈值过滤。阈值区间召回倾向适用场景0.80 以上高精度、低召回答案必须出现在原文不允许模型发挥0.65 到 0.75均衡企业内部制度问答默认推荐0.50 以下高召回、高噪声文档稀少宁可多给上下文让模型判断多轮对话中的“翻译”更加重要。用户问完“报销流程”再问“要提前多久”直接把“要提前多久”拿去检索大概率失败。正确做法是先调用一个改写函数把问题补全成“报销流程需要提前多久提交”再进入检索。这个改写任务可以复用同一个 Kernel用一条独立提示词完成。FastWiki 类源码中的Chat模块通常会有类似context_dialogue的参数传递本质上就是在控制这个改写粒度。4.2 用 KernelFunction 把向量检索暴露给模型在最小链路基础上把检索动作封装成插件函数模型才能按需调用。下面这个WikiSearchPlugin接收用户问题返回检索到的文本片段using Microsoft.SemanticKernel; using Microsoft.SemanticKernel.Memory; public sealed class WikiSearchPlugin { private readonly ISemanticTextMemory _memory; public WikiSearchPlugin(ISemanticTextMemory memory) { _memory memory; } [KernelFunction(wiki_search)] [Description(从企业知识库中检索与问题相关的文档片段返回纯文本必须包含上下文)] public async Taskstring SearchAsync( [Description(用户问题需要包含完整语境)] string query, int top 3, CancellationToken cancellationToken default) { var results await _memory.SearchAsync( collection: wiki, query: query, limit: top, minRelevanceScore: 0.70, cancellationToken: cancellationToken); return string.Join(\n, results.Select(r $【相关度 {r.RelevanceScore:P0}】{r.Metadata.Text})); } }在构建 Kernel 时注册插件var kernel Kernel.CreateBuilder() .AddOpenAITextGeneration(modelId, apiKey) .Build(); kernel.Plugins.AddFromTypeWikiSearchPlugin(new WikiSearchPlugin(memory));这里AddFromTypeT会根据[KernelFunction]自动扫描公开方法。top参数直接控制送入提示词的切片数量默认 3 是比较折中的选择。[Description]中强调“必须包含上下文”是防止模型把检索工具当作闲聊助手。如果函数描述写成“搜索知识库”模型在日常问候场景也可能发起一次无用检索浪费 token 还拖慢响应。4.3 提示词模板与 KernelArguments 注入插件负责带回素材提示词模板负责限定模型怎么用素材。我常用的模板风格是把格式约束写清楚让模型在资料不足时明确拒绝回答。var prompt 你是企业知识库助手只能基于下面的资料回答回答问题后必须给出资料片段编号。 context {{$context}} /context 用户问题{{$question}} 规则 1. 资料中没有提到的内容回答“未在知识库中找到相关内容”。 2. 不要编造条款、数字或流程。 3. 引用资料时要保留原文关键词。 ; var arguments new KernelArguments { [question] 报销单需要谁签字, [context] await wikiSearchPlugin.SearchAsync(报销单需要谁签字, top: 3) }; var reply await kernel.InvokePromptAsync(prompt, arguments); Console.WriteLine(reply.GetValuestring());{{$context}}和{{$question}}是模板变量KernelArguments以字典形式注入。Semantic Kernel 会在发起模型调用前完成模板渲染所以这里不存在 SQL 拼串式注入风险。context的值来自身插件返回的文本顺序按相关度从高到低排列模型通常更重视出现在靠前位置的片段因此插件内部要把minRelevanceScore过滤放在排序之前。reply.GetValuestring()拿到的是模型文本输出调试时先确认它不为空再去查提示词是否有违规格式要求。这条链路跑通之后知识库系统已经具备基本的问答能力剩下的就是打磨会话历史和资源开销。5. 源码级优化缓存、令牌配额与排错技巧5.1 并发嵌入的缓存避免同一个切片反复向量化知识库重新导入时大量切片内容不会变化但嵌入模型的调用成本却会重复产生。我会在嵌入服务外面套一层ConcurrentDictionary缓存用文本本身作为键名。异步场景下直接用GetOrAdd会踩到重复计算的坑更可靠的做法是用LazyTask...包住异步任务using System.Collections.Concurrent; private readonly ConcurrentDictionarystring, LazyTaskReadOnlyMemoryfloat _cache new(); public async TaskReadOnlyMemoryfloat GetCachedEmbeddingAsync(string text) { var lazy _cache.GetOrAdd( text, new LazyTaskReadOnlyMemoryfloat(() EmbedTextAsync(text))); return await lazy.Value; }GetOrAdd的第二个参数只在键不存在时执行所以同一时刻多个线程拿到同一个LazyTaskawait lazy.Value也只会触发一次真实嵌入调用。这样改完后重复文档或增量更新都能跳过昂贵计算。需要注意缓存不能放在 Web 层否则扩容后每台机器各存一份应该放进 Infrastructure 层的嵌入服务实现里。5.2 给上下文设置令牌硬上限生成模型的输入令牌不是无限的知识库召回 3 到 5 个切片后很容易超过模型上下文窗口。最直接的做法是先用分词器估算令牌数再按配额截断。用 SharpToken 这类库读取 OpenAI 的 BPE 编码代码很简单using SharpToken; var encoding GptEncoding.GetEncoding(cl100k_base); var tokenCount encoding.CountTokens(contextText); const int maxContextTokens 3000; if (tokenCount maxContextTokens) { contextText contextText[..Math.Min(contextText.Length, maxContextTokens * 2)]; }cl100k_base是多个 GPT 模型共用的词表。这里按“1 个中文汉字约为 1 到 2 个 token”做粗估实际值要在接入模型后校准。更严谨的做法是在检索阶段按字符数预筛只保留相关度最高的切片而不是把所有切片全部塞入上下文。令牌配额一旦写死就要在配置中心暴露为可调项因为模型版本升级后上下文窗口可能改变。5.3 从源码视角排查三个高频问题遇到回答胡说先别急着改提示词。我会按下面顺序排查先看minRelevanceScore是不是太低导致噪声进了上下文再看context里是否真的包含答案原文最后才怀疑生成模型本身。回答为空则检查KernelArguments里变量名是否和模板中的{{$...}}一一对应。响应慢则重点看是不是每次请求都在重新向量化用户问题用户问题本身也应该加短时缓存。这三个问题在源码里对应的位置很清晰检索实现、提示词渲染、嵌入调用。调试时打开 Semantic Kernel 的IDiagnosticLogger把它输出到控制台观察每一次函数调用和令牌消耗。与其反复试探模型温度参数不如把日志和检索结果先摆到眼前大多数知识库坏在数据准备而不是模型选型。本文还有配套的精品资源点击获取
基于Semantic Kernel与.NET 8的企业知识库语义问答系统设计
简介基于微软Semantic Kernel和.NET 8构建的FastWiki知识库系统完整设计源码面向需要搭建智能知识检索平台的.NET开发者及希望掌握语义内核落地技巧的架构师。项目以后端框架MasaFramework和前端框架React为双核心专注于深度学习与自然语言处理场景旨在提供高效、易用且可扩展的智能向量搜索方案帮助团队快速实现知识库的语义化检索与问答。整个zip压缩包共包含917个文件包体仅3.37MB其中386个TypeScript源文件与265个TSX模板文件用于构建前端界面172个C#源文件承载后端业务逻辑、数据库上下文和迁移版本61个JSON配置文件管理依赖与运行参数另含csproj项目文件、Dockerfile容器化配置和gitmodules子模块引用目录划分清晰便于按层次阅读。已有232人学习下载。研读源码可以完整掌握基于语义内核的知识库设计思路包括向量化分块、嵌入生成、相似度检索、问答提示词编排等核心流程同时看到从数据库初始化到字段调整的开发细节适合企业级知识库系统的二次开发与功能扩展。1. Semantic Kernel 和 FastWiki 知识库系统为什么要在 .NET 8 里做语义问答很多团队其实已经有“知识库”了一堆 Markdown 文档、企业 wiki、PDF 制度文件搜索靠数据库LIKE或者 Elasticsearch 分词。问题是用户问“今年报销流程有没有变”关键词搜出来的是去年的旧政策用户要的是“哪一条规则能回答我的问题”不是“哪些文件包含报销两个字”。FastWiki 这种项目的价值是把 Microsoft Semantic Kernel 当作编排层在 .NET 8 进程内完成从文档加载、向量化、语义检索到生成回答的完整链路。它适合两种人一种是给内部做知识库但不想把文档内容直接交给外部问答服务的团队另一种是已经用 C# 技术栈、想通过源码设计把握 RAG 数据流而不是只调 API 的开发。这个系统的核心矛盾不在大模型本身而在切片是否准、召回是否对、提示词有没有让模型知道什么时候该闭嘴。2. .NET 8 项目拆分与 Semantic Kernel 的最小运行链路2.1 从源码模块看 FastWiki 类项目的引用方向Core、Infrastructure、Web我读一个 .NET 源码项目时不会先按文件名找实现而是先看.csproj里的ProjectReference方向。FastWiki 这类知识库系统通常拆成四层Core只放实体、接口和领域规则Infrastructure负责向量库、文件存储、PDF 解析这些可替换实现Service编排导入、检索和问答用例Web只暴露 HTTP API 和后台任务。这样拆不是为了分层而分层而是因为知识库系统功能面太杂导入、解析、切分、向量化、召回、对话、权限、审计每一步都可能换实现比如从 Qdrant 换到 Azure AI Search不能牵连对话编排代码。刚上手时容易掉进“源码在哪个工程”的迷宫这和读大型 C 项目要从构建脚本切入一样。在 .NET 8 里最直接的入口是找DependencyInjection扩展方法比如AddWikiCore()、AddInfrastructure()它们决定接口与实现的绑定关系。以 FastWiki 的设计思路看Kernel对象不会在 Web 层直接new出来而是由基础设施层注册成单例并通过一个端口接口暴露给用例层。这样做的收益很实际单元测试时可以把向量库换成VolatileMemoryStore把嵌入模型换成固定向量跑完一轮切分和检索用例。2.2 Kernel.CreateBuilder 最小链路模型、API Key、执行一次回答先跑通最小链路再谈优化。下面代码是 .NET 8 控制台项目里最小可运行的 Semantic Kernel 调用目标是把“提示词渲染 → 模型生成 → 输出结果”这条链路在本地立起来。using Microsoft.SemanticKernel; const string modelId gpt-4o-mini; const string apiKey your-api-key; var kernel Kernel.CreateBuilder() .AddOpenAITextGeneration(modelId, apiKey) .Build(); var result await kernel.InvokePromptAsync(用一句话解释知识库分块的作用); Console.WriteLine(result);Kernel.CreateBuilder()是 Semantic Kernel 1.x 的构建入口效果类似于 ASP.NET Core 的WebApplication.CreateBuilder。AddOpenAITextGeneration注册的是“文本生成服务”负责把渲染后的提示词发给模型。这里modelId和apiKey只是形参实际开发中必须从IConfiguration和用户机密里读取不能写死在源码里。但知识库系统只注册文本生成不够后面向量化还需要嵌入模型。常见做法是同时注册两个服务var kernel Kernel.CreateBuilder() .AddOpenAITextGeneration(modelId: gpt-4o-mini, apiKey: apiKey) .AddOpenAITextEmbeddingGeneration(modelId: text-embedding-3-small, apiKey: apiKey) .Build();AddOpenAITextEmbeddingGeneration注册的是嵌入生成服务输入一段文本输出一个浮点数组也就是向量。这里提醒一个容易混淆的配置项文本生成模型和嵌入模型通常是两个不同型号很多团队误以为只配一个 GPT 模型就能做语义检索结果在向量化阶段反复报维度错误。在 FastWiki 类项目的源码里这两个服务注册位置不会放在同一个方法里因为文本生成模型可能被替换成本地模型而嵌入模型可能因成本原因换成开源模型需要独立开关。2.3 Kernel 的函数标注为什么要给模型“说明书”Semantic Kernel 和普通 HTTP 调 OpenAI 最大的区别是它可以管理“函数”。函数分三类提示词函数、原生函数、插件。知识库系统最核心的是原生函数也就是用 C# 方法完成向量检索再让模型决定是否调用它。为了让模型正确调用方法上必须写清函数名和描述。using Microsoft.SemanticKernel; public sealed class WikiStatusPlugin { [KernelFunction(get_knowledge_base_status)] [Description(返回知识库中最近一次索引完成的时间和文档数量)] public string GetStatus() { return 最近索引时间2025-01-15 08:30文档数量128; } }[KernelFunction]参数决定模型看到的函数名[Description]是给模型看的功能说明书。模型不是通过编译期强类型知道该调用谁而是根据描述文本判断。描述写得越具体调用准确率越高。比如把“返回知识库状态”改成“返回知识库中最近一次索引完成的时间和文档数量”模型在用户问“索引更新了吗”时就更容易命中这个函数。这里的wiki前缀只是属性参数不参与目录结构。后续章节中我会把真正的向量检索函数留给 RAG 链路使用这里先说明函数注册与模型调度的边界。模型可见名称说明对象典型失败点[KernelFunction]函数名决定模型在 JSON 调用中填什么用中文名可能导致模型生成非法标识符[Description]函数行为说明描述太短模型在多个函数间选择错误[Parameter]上的描述参数含义与格式参数含义不清模型传错字符串注册插件使用kernel.Plugins.AddFromTypeWikiStatusPlugin()之后模型会在判断需要该能力时自动调用。需要注意的是这种调用不是每次必发生模型可能直接回答也可能调用多个函数。后面的 RAG 链路本质上是把“检索”这个动作也变成函数并和提示词模板串在一起。理解了这条边界再去看 FastWiki 的源码你看到的就不是一个个散落的类而是一张“函数注册表 提示词模板 向量库”的关系网。3. 知识库核心文档解析、切片与向量化存储3.1 文档解析的输入输出约定统一成纯文本FastWiki 这类系统的输入文件五花八门最常见的是 PDF、Word、Markdown、TXT。如果每个业务方法都直接处理文件流代码会被各种解析库的using淹没。我一般会先定一个统一接口所有解析器都输出纯文本并且保留段落顺序和必要的标题层级。public interface ITextExtractor { string Extract(Stream fileStream, string fileName); }Extract接收文件流和文件名文件名用于判断解析类型。PDF 可以用 PdfPig 或 PdfPlex 这类库处理但要注意 PDF 经常没有可靠的文字层扫描件必须走 OCR这是一条完全不同的管线。Word 可以用 Open XML SDKMarkdown 和 TXT 直接读字符流后做编码转换。接口的价值在于下游分块器只认字符串不关心文件是从哪个格式来的。解析完成后建议顺手记录两个元数据来源文件名和页面或章节号。这样后续回答可以溯源到具体文档用户不会接受“AI 说应该这样做”却看不到出处。在源码设计里元数据会随着文本切片一起写入向量库形成一条从回答到原文档的引用链。3.2 分块Chunking策略固定窗口与重叠参数的取舍这是整个知识库工程里最容易被低估的环节。模型一次能接收的上下文有限向量检索的召回粒度也决定了回答质量。我见过的错误做法是把整个章节塞进一个向量结果一个切片几千字检索时相关片段被无关内容稀释生成阶段又截断。常用的兜底方案是固定字符窗口加重叠。以下代码按最大字符数切分并让相邻切片保留一段重叠文字public static Liststring SplitText(string text, int maxChars, int overlapChars) { var chunks new Liststring(); var start 0; while (start text.Length) { var length Math.Min(maxChars, text.Length - start); var chunk text.Substring(start, length); if (!string.IsNullOrWhiteSpace(chunk)) { chunks.Add(chunk); } if (start length text.Length) { break; } start length - overlapChars; } return chunks; }参数maxChars控制每个向量的内容长度。知识库场景里500 到 800 字符的切片比 2000 字符切片更容易命中精确答案。overlapChars让相邻切片共用几十个字符避免一个问题中涉及的关键描述恰好被截断成两半。这里给出一组常用起始参数具体还是要按你的文档语言和句式习惯调。参数推荐起点增大效果减小效果maxChars600上下文更完整但向量噪声增加精确率上升但检索片段过于碎片overlapChars80降低截断风险节省向量存储空间minRelevanceScore0.70回答更谨慎漏召回回答容易说“找不到”固定窗口只是兜底。如果原始文档是 Markdown 或带标题的结构化内容最好先按一级标题切一次再用固定窗口处理过长的段落。FastWiki 类项目源码中值得读的部分往往不是解析库的封装而是这个“标题切分 长度重叠”的组合函数它决定了后面每一步的上限。3.3 向量化与存储从 VolatileMemoryStore 到生产向量库分块完成后每一段文本都要交给嵌入模型生成向量再写入向量存储。语义检索不依赖关键词完全一致而是比较向量距离所以“报销流程”和“费用申请流程”也能被关联起来。先看一个不依赖外部数据库的最小实现非常适合本地调试和自动化测试using Microsoft.SemanticKernel.Connectors.OpenAI; using Microsoft.SemanticKernel.Memory; using Microsoft.SemanticKernel; const string apiKey your-api-key; var embeddingGenerator new OpenAITextEmbeddingGeneration( modelId: text-embedding-3-small, apiKey: apiKey); var memoryStore new VolatileMemoryStore(); var memory new SemanticTextMemory(memoryStore, embeddingGenerator); await memory.SaveInformationAsync( collection: wiki, text: 报销单需要部门主管签字后才能提交财务。, id: policy-001, description: 报销制度-签字流程); var results await memory.SearchAsync( collection: wiki, query: 报销找谁签字, limit: 3, minRelevanceScore: 0.70); foreach (var item in results) { Console.WriteLine(${item.Metadata.Text} | 相关度 {item.RelevanceScore:P0}); }collection是命名空间相当于数据库里的表id必须唯一description是供检索和展示使用的辅助文本。SearchAsync的query是用户原话limit控制返回条数minRelevanceScore是召回质量门槛。如果阈值设得太低垃圾片段会进入提示词回答容易胡编设得太高又可能召回为空模型只能回答“不知道”。VolatileMemoryStore把向量存在内存里进程一重启就清空所以它只适合验证链路。生产环境需要把VolatileMemoryStore换成正经向量库。Semantic Kernel 1.x 的IMemoryStore提供统一接口常见选择有 Qdrant、Azure AI Search、PostgreSQL pgvector。选型时看三个纬度选型维度检查项部署方式能否在既有内网环境部署是否强制走外部 SaaS向量维度嵌入模型的输出维度是否在向量库支持范围内过滤能力是否支持按权限、部门、文档来源做混合过滤很多团队在本地调试时用内存库跑通上线前才接入 Qdrant这是最稳的路径。注意不同版本下连接器类名会有迁移源码阅读时不要死记QdrantMemoryStore还是QdrantVectorStore重点看IMemoryStore的实现类注册在哪个模块。只要能满足SaveInformationAsync和SearchAsync两个操作上层代码就不需要大改。4. 检索问答Semantic Kernel 的 RAG 调用链与提示词设计4.1 召回链路从问题到上下文的两次“翻译”知识库问答不是简单地把用户问题塞给模型。完整链路是先把原始问题转成一个适合向量检索的表达再从向量库召回最相关的切片最后把切片作为上下文连同用户问题一起交给生成模型。第二步与第三步之间还有一个容易被忽略的环节阈值过滤。阈值区间召回倾向适用场景0.80 以上高精度、低召回答案必须出现在原文不允许模型发挥0.65 到 0.75均衡企业内部制度问答默认推荐0.50 以下高召回、高噪声文档稀少宁可多给上下文让模型判断多轮对话中的“翻译”更加重要。用户问完“报销流程”再问“要提前多久”直接把“要提前多久”拿去检索大概率失败。正确做法是先调用一个改写函数把问题补全成“报销流程需要提前多久提交”再进入检索。这个改写任务可以复用同一个 Kernel用一条独立提示词完成。FastWiki 类源码中的Chat模块通常会有类似context_dialogue的参数传递本质上就是在控制这个改写粒度。4.2 用 KernelFunction 把向量检索暴露给模型在最小链路基础上把检索动作封装成插件函数模型才能按需调用。下面这个WikiSearchPlugin接收用户问题返回检索到的文本片段using Microsoft.SemanticKernel; using Microsoft.SemanticKernel.Memory; public sealed class WikiSearchPlugin { private readonly ISemanticTextMemory _memory; public WikiSearchPlugin(ISemanticTextMemory memory) { _memory memory; } [KernelFunction(wiki_search)] [Description(从企业知识库中检索与问题相关的文档片段返回纯文本必须包含上下文)] public async Taskstring SearchAsync( [Description(用户问题需要包含完整语境)] string query, int top 3, CancellationToken cancellationToken default) { var results await _memory.SearchAsync( collection: wiki, query: query, limit: top, minRelevanceScore: 0.70, cancellationToken: cancellationToken); return string.Join(\n, results.Select(r $【相关度 {r.RelevanceScore:P0}】{r.Metadata.Text})); } }在构建 Kernel 时注册插件var kernel Kernel.CreateBuilder() .AddOpenAITextGeneration(modelId, apiKey) .Build(); kernel.Plugins.AddFromTypeWikiSearchPlugin(new WikiSearchPlugin(memory));这里AddFromTypeT会根据[KernelFunction]自动扫描公开方法。top参数直接控制送入提示词的切片数量默认 3 是比较折中的选择。[Description]中强调“必须包含上下文”是防止模型把检索工具当作闲聊助手。如果函数描述写成“搜索知识库”模型在日常问候场景也可能发起一次无用检索浪费 token 还拖慢响应。4.3 提示词模板与 KernelArguments 注入插件负责带回素材提示词模板负责限定模型怎么用素材。我常用的模板风格是把格式约束写清楚让模型在资料不足时明确拒绝回答。var prompt 你是企业知识库助手只能基于下面的资料回答回答问题后必须给出资料片段编号。 context {{$context}} /context 用户问题{{$question}} 规则 1. 资料中没有提到的内容回答“未在知识库中找到相关内容”。 2. 不要编造条款、数字或流程。 3. 引用资料时要保留原文关键词。 ; var arguments new KernelArguments { [question] 报销单需要谁签字, [context] await wikiSearchPlugin.SearchAsync(报销单需要谁签字, top: 3) }; var reply await kernel.InvokePromptAsync(prompt, arguments); Console.WriteLine(reply.GetValuestring());{{$context}}和{{$question}}是模板变量KernelArguments以字典形式注入。Semantic Kernel 会在发起模型调用前完成模板渲染所以这里不存在 SQL 拼串式注入风险。context的值来自身插件返回的文本顺序按相关度从高到低排列模型通常更重视出现在靠前位置的片段因此插件内部要把minRelevanceScore过滤放在排序之前。reply.GetValuestring()拿到的是模型文本输出调试时先确认它不为空再去查提示词是否有违规格式要求。这条链路跑通之后知识库系统已经具备基本的问答能力剩下的就是打磨会话历史和资源开销。5. 源码级优化缓存、令牌配额与排错技巧5.1 并发嵌入的缓存避免同一个切片反复向量化知识库重新导入时大量切片内容不会变化但嵌入模型的调用成本却会重复产生。我会在嵌入服务外面套一层ConcurrentDictionary缓存用文本本身作为键名。异步场景下直接用GetOrAdd会踩到重复计算的坑更可靠的做法是用LazyTask...包住异步任务using System.Collections.Concurrent; private readonly ConcurrentDictionarystring, LazyTaskReadOnlyMemoryfloat _cache new(); public async TaskReadOnlyMemoryfloat GetCachedEmbeddingAsync(string text) { var lazy _cache.GetOrAdd( text, new LazyTaskReadOnlyMemoryfloat(() EmbedTextAsync(text))); return await lazy.Value; }GetOrAdd的第二个参数只在键不存在时执行所以同一时刻多个线程拿到同一个LazyTaskawait lazy.Value也只会触发一次真实嵌入调用。这样改完后重复文档或增量更新都能跳过昂贵计算。需要注意缓存不能放在 Web 层否则扩容后每台机器各存一份应该放进 Infrastructure 层的嵌入服务实现里。5.2 给上下文设置令牌硬上限生成模型的输入令牌不是无限的知识库召回 3 到 5 个切片后很容易超过模型上下文窗口。最直接的做法是先用分词器估算令牌数再按配额截断。用 SharpToken 这类库读取 OpenAI 的 BPE 编码代码很简单using SharpToken; var encoding GptEncoding.GetEncoding(cl100k_base); var tokenCount encoding.CountTokens(contextText); const int maxContextTokens 3000; if (tokenCount maxContextTokens) { contextText contextText[..Math.Min(contextText.Length, maxContextTokens * 2)]; }cl100k_base是多个 GPT 模型共用的词表。这里按“1 个中文汉字约为 1 到 2 个 token”做粗估实际值要在接入模型后校准。更严谨的做法是在检索阶段按字符数预筛只保留相关度最高的切片而不是把所有切片全部塞入上下文。令牌配额一旦写死就要在配置中心暴露为可调项因为模型版本升级后上下文窗口可能改变。5.3 从源码视角排查三个高频问题遇到回答胡说先别急着改提示词。我会按下面顺序排查先看minRelevanceScore是不是太低导致噪声进了上下文再看context里是否真的包含答案原文最后才怀疑生成模型本身。回答为空则检查KernelArguments里变量名是否和模板中的{{$...}}一一对应。响应慢则重点看是不是每次请求都在重新向量化用户问题用户问题本身也应该加短时缓存。这三个问题在源码里对应的位置很清晰检索实现、提示词渲染、嵌入调用。调试时打开 Semantic Kernel 的IDiagnosticLogger把它输出到控制台观察每一次函数调用和令牌消耗。与其反复试探模型温度参数不如把日志和检索结果先摆到眼前大多数知识库坏在数据准备而不是模型选型。本文还有配套的精品资源点击获取
)
)
