1. 项目概述一个为Elixir生态量身打造的嵌入式RAG库如果你正在用Elixir和Phoenix构建应用并且想为它加上一个智能的“知识大脑”让应用能理解、检索并回答用户基于你私有数据的问题那么Arcana就是你一直在找的那个工具。它不是一个需要你额外维护一个Python服务、一个独立向量数据库的“外挂”系统而是一个能直接嵌入到你现有Phoenix应用生命周期的原生库。简单来说Arcana让你能用Elixir的方式在BEAM虚拟机上构建从文档处理、向量化、知识图谱到智能检索与生成RAG的完整能力所有数据都存放在你已有的PostgreSQL数据库中。为什么这很重要传统的RAG方案往往意味着技术栈的割裂用Python写数据处理和模型服务用HTTP与你的主应用通信再单独维护一个向量数据库如Pinecone、Weaviate。这不仅增加了运维复杂度也让调试、监控和事务一致性变得棘手。Arcana的核心哲学是“一体化”你的Ecto仓库Repo就是向量存储你的Phoenix监督树Supervision Tree承载着嵌入模型和重排序器你的LiveView可以直接变身管理面板而应用内建的Telemetry则提供了完整的可观测性。它充分利用了Elixir/OTP在并发、容错和热升级方面的天然优势将RAG从一个外部服务变成了应用的一个有机组成部分。2. 核心设计理念为何选择“嵌入式”与“一体化”2.1 技术栈统一的优势在深入代码之前理解Arcana的设计选择至关重要。大多数RAG库诞生于Python生态这本身无可厚非因为AI模型生态的重心在那里。但当你要将其集成到一个Elixir/Phoenix应用中时就会面临“胶水代码”的困境数据需要在两个系统间同步错误处理需要跨进程协调链路追踪变得支离破碎。Arcana的创始人George Guimarães敏锐地意识到BEAM虚拟机Erlang运行时的特性——轻量级进程、监督树、内置的:telemetry——本身就是构建稳健、可观测的RAG系统的绝佳基础。一个Repo统治所有Arcana将文档、文本块Chunk、向量嵌入、实体关系等所有数据都通过迁移文件创建为标准的Ecto Schema存储在同一个PostgreSQL数据库中并利用pgvector扩展来处理向量相似度搜索。这意味着数据一致性文档的增删改查可以与你的用户、订单等业务数据在同一个数据库事务中完成。简化运维无需部署、监控另一个数据库服务。备份、恢复、连接池管理都是你熟悉的那一套。利用现有技能你的团队不需要学习新的查询语言或管理工具用Ecto和SQL就能操作所有RAG相关数据。本地优先的计算Arcana默认使用BumblebeeElixir的神经网络库在本地运行嵌入模型和交叉编码器Cross-Encoder重排序模型。它支持NxElixir的数值计算库的后端如EXLA用于GPU/TPU加速、EMLX针对Apple Silicon优化和Torchx。这带来了显著的延迟降低和成本节省尤其对于处理敏感数据或需要高频调用的场景。当然它也完全支持切换到OpenAI、Cohere等云端API但这只是一个可选项而非必选项。2.2 面向不同场景的三种使用模式Arcana没有提供“一刀切”的接口而是根据任务的复杂度和对控制流的需求提供了三个层次的使用界面这直接对应了学术界对Agentic RAG的分类。2.2.1 高级RAG模式Arcana.search/2与Arcana.ask/2这是最常用的入口对应“Advanced RAG”。你只需要一个函数调用它内部就自动完成了查询重写、混合搜索向量全文、可选的图谱融合以及交叉编码器重排序。适合绝大多数问答和检索场景。例如用户问“Phoenix怎么处理实时更新”Arcana.ask/2会先将其重写为更规范的查询语句然后从你的知识库中检索相关片段最后让LLM生成一个连贯的答案。2.2.2 模块化RAG模式Arcana.Pipeline当你需要对检索-生成流程的每一步进行精细控制时就该使用Arcana.Pipeline了它对应“Modular RAG”。你可以像组装乐高一样自定义流程的步骤和顺序。Pipeline暴露了从gate判断是否需要检索、rewrite查询重写、decompose问题分解、search、rerank到answer生成和ground事实性核查的每一个环节。每个环节都是一个行为Behaviour你可以用短短十几行代码实现自己的逻辑来替换默认实现。这为处理复杂查询如需要多步推理的比较性问题提供了极大的灵活性。2.2.3 智能体RAG模式Arcana.Loop这是最前沿的模式对应“Agentic RAG”。在这种模式下控制权被交给了LLM本身。你向Arcana.Loop提出一个开放性问题例如“找出所有博士被同伴背叛的剧集”然后启动循环。在每一轮迭代中一个作为“控制器”的LLM通常选用较小、较快的模型会评估当前上下文并自主决定调用哪个工具search继续搜索、answer给出最终答案或give_up放弃。它可能会进行多轮搜索逐步收集信息直到认为自己可以回答或达到迭代上限。这种模式特别适合答案隐藏在多次“跳跃”Multi-hop检索中的复杂问题。3. 实战入门从零开始集成Arcana3.1 环境准备与安装假设你已经有一个正在运行的Phoenix 1.7应用并且使用PostgreSQL作为数据库。集成Arcana最快捷的方式是使用Igniter一个Elixir项目模板工具。# 在你的Phoenix项目根目录下执行 mix igniter.install arcana这个命令会完成以下几件事在mix.exs中添加Arcana依赖。生成数据库迁移文件用于创建documents、chunks、embeddings、entities等表。在config/config.exs中为你的Repo添加Arcana.Repo配置。在lib/your_app/application.ex的监督树中启动必要的Arcana服务如嵌入服务。在router.ex中挂载Arcana的LiveView管理面板路由。接下来运行迁移以创建表结构mix ecto.migrate手动安装详解如果你希望更细致地控制或者项目结构特殊也可以手动安装。核心步骤包括添加依赖在mix.exs的deps函数中添加{:arcana, ~ 0.1}。配置数据库确保你的config/dev.exs等环境配置中为Ecto Repo启用了pgvector扩展。这通常在Repo配置的after_connect回调中完成。配置嵌入服务这是关键一步。你需要在application.ex的start/2函数中将嵌入服务Arcana.Embedder和重排序服务Arcana.Reranker作为子进程启动。Arcana提供了Arcana.Embedder.Bumblebee等实现你需要指定使用的模型如Bumblebee.Models.HfTextEmbedding.all_minilm_l6_v2()。运行迁移手动复制Arcana提供的迁移文件到你的priv/repo/migrations目录并执行mix ecto.migrate。3.2 首次数据摄入与查询安装并启动服务后你就可以开始向知识库添加内容了。数据摄入Ingestion是构建RAG系统的第一步。3.2.1 摄入纯文本最简单的方式是直接摄入一段文本。Arcana会自动将其分块、生成向量并存储。# 在IEx中或你的业务逻辑中 alias MyApp.Repo {:ok, document} Arcana.ingest( Phoenix LiveView 是一个用于构建实时、服务器渲染用户界面的Elixir库。 它消除了对客户端JavaScript框架的依赖通过持久的WebSocket连接在服务器和客户端之间同步状态。 LiveView的核心是“状态在服务端DOM差异通过WebSocket推送”的模型。 , repo: Repo, collection: elixir-guides # 可选将文档归类到某个集合中 )ingest/2函数会返回一个{:ok, %Arcana.Document{}}元组。在后台它完成了分块使用默认或配置的分块器Chunker将长文本切割成有重叠的小段以优化检索效果。嵌入调用你配置的嵌入服务为每个文本块生成高维向量。存储将文档元数据、文本块和对应的向量存入数据库。3.2.2 进行首次智能问答数据摄入后立刻就可以进行查询。# 使用最简单的 ask/2 接口 {:ok, answer_ctx} Arcana.ask(Phoenix LiveView 是什么, repo: Repo, llm: openai:gpt-4o-mini # 指定使用的LLM格式为 提供商:模型名 ) IO.puts answer_ctx.answer # 输出可能类似于“Phoenix LiveView 是一个允许开发者使用Elixir构建实时、交互式Web界面的库...”ask/2在内部调用了search/2进行检索然后将检索到的相关文本块作为上下文连同问题一起发送给LLM生成答案。你还可以通过search/2直接获取检索结果而不生成答案用于构建自定义的交互流程。3.3 核心配置详解嵌入模型与LLM提供商嵌入模型配置Arcana的威力很大程度上取决于嵌入模型的质量。本地运行all-MiniLM-L6-v2是一个不错的起点它在速度和效果上取得了很好的平衡。配置在config/config.exs中config :arcana, :embedder, serving: [ module: Arcana.Embedder.Bumblebee, model: {sentence-transformers/all-MiniLM-L6-v2, Bumblebee.Models.HfTextEmbedding.all_minilm_l6_v2()}, batch_size: 32, defn_options: [compiler: EXLA] # 使用EXLA编译器进行GPU加速 ]如果你的机器有NVIDIA GPU使用EXLA后端可以极大提升向量化速度。对于Apple Silicon Mac可以配置为EMLX。LLM提供商集成Arcana通过Arcana.LLM行为抽象了与不同大模型API的交互。它内置了OpenAI、Anthropic、Z.ai等提供商的适配器。配置通常在环境变量或runtime.exs中完成config :arcana, :llm_providers, openai: [ api_key: System.get_env(OPENAI_API_KEY), http_options: [recv_timeout: 60_000] ], anthropic: [ api_key: System.get_env(ANTHROPIC_API_KEY) ]在调用ask/2或Loop.run/2时通过llm: openai:gpt-4o这样的字符串来指定模型。你也可以实现自己的Arcana.LLM行为接入任何兼容的API或本地模型。注意初次运行涉及模型下载。Bumblebee会从Hugging Face下载模型文件这可能需要一些时间请确保网络通畅。模型文件默认会缓存在~/.cache/bumblebee目录下。4. 深入核心Pipeline模块化流程实战当你需要超越简单的问答处理更复杂的检索任务时Arcana.Pipeline提供了完整的控制力。它本质上是一个可组合的数据处理管道上下文%Pipeline.Context{}在其中流动并被逐步丰富。4.1 Pipeline 基础流程解析一个典型的Pipeline调用看起来像这样alias Arcana.Pipeline # 1. 创建初始上下文 ctx Pipeline.new(比较Elixir和Erlang在构建Web服务方面的优缺点, repo: MyApp.Repo, llm: openai:gpt-4o-mini ) # 2. 执行管道步骤 ctx ctx | Pipeline.rewrite() # 步骤A重写查询使其更规范 | Pipeline.select(collections: [elixir, erlang]) # 步骤B让LLM选择在哪个集合中搜索 | Pipeline.decompose() # 步骤C将复杂问题分解成子问题 | Pipeline.search() # 步骤D并行搜索所有子问题 | Pipeline.rerank() # 步骤E对搜索结果进行重排序 | Pipeline.answer() # 步骤F综合所有信息生成最终答案 | Pipeline.ground() # 步骤G可选进行事实性核查 # 3. 获取结果 final_answer ctx.answer grounding_score ctx.grounding.score # 事实性得分越高越好让我们拆解每个关键步骤rewrite/1: 用户的问题往往是口语化的、模糊的。此步骤利用LLM将问题重写为更适合检索的形式。例如“咋用LiveView搞个聊天室”可能被重写为“如何使用Phoenix LiveView实现一个实时聊天室应用”decompose/1: 对于复合型问题如上面的比较问题这一步会将其分解为多个独立的子问题例如[“Elixir构建Web服务的优势是什么”“Erlang构建Web服务的优势是什么”“两者的主要区别是什么”]。这些子问题会被并行搜索效率远高于用原问题一次性检索。search/1: 这是核心检索步骤。它对每一个子问题或原问题执行混合搜索。默认情况下它同时进行向量语义搜索计算查询的向量在pgvector中查找余弦相似度最高的文本块。全文搜索利用PostgreSQL的tsvector/tsquery进行关键词匹配。结果融合使用** Reciprocal Rank Fusion (RRF)** 算法将两种检索方式的结果列表融合成一个更优的最终排名。RRF能有效结合语义相关性和关键词匹配度。rerank/1: 初步检索返回的Top-K个结果比如20个可能包含一些相关性稍差的片段。重排序步骤使用一个更精细的交叉编码器模型如cross-encoder/ms-marco-MiniLM-L-6-v2对查询和每一个候选片段进行两两交互计算得到一个更精确的相关性分数并据此重新排序。这通常能显著提升Top-1结果的准确率。answer/1: 将经过重排序的最相关文本块作为上下文连同问题一起发送给LLM指令其生成最终答案。你可以通过max_tokens、temperature等参数控制生成过程。ground/1: 这是一个可选的“守门员”步骤。它使用自然语言推理模型来判断生成的答案是否严格基于提供的上下文。如果答案中包含了上下文未提及的信息即“幻觉”则会给出一个较低的分数。这对于需要高事实准确性的场景如客服、知识库至关重要。4.2 自定义Pipeline行为Pipeline的强大之处在于它的每个步骤都是可插拔的。每个步骤都对应一个行为Behaviour例如Arcana.Pipeline.Step.Rewrite。默认实现已经足够好但当你需要特殊逻辑时可以轻松覆盖。假设你的应用领域有特殊的术语需要定制的查询重写规则defmodule MyApp.CustomRewriter do behaviour Arcana.Pipeline.Step.Rewrite impl true def call(%Pipeline.Context{query: query} ctx, _opts) do # 1. 先进行一些领域特定的字符串替换 enhanced_query String.replace(query, 咱这系统, 本订单管理系统) enhanced_query String.replace(enhanced_query, 卡单, 订单状态停滞) # 2. 再调用默认的LLM重写逻辑可选也可以完全自己实现 # 这里我们复用Arcana内置的LLM重写器但传入我们预处理后的查询 new_ctx %Pipeline.Context{ctx | query: enhanced_query} Arcana.Pipeline.Step.Rewrite.Default.call(new_ctx, []) end end # 使用自定义的重写器 ctx | Pipeline.rewrite(using: MyApp.CustomRewriter) | ... # 其他步骤你可以用同样的方式自定义分块策略、搜索算法例如集成一个外部搜索引擎、重排序模型甚至整个答案生成的提示词模板。这种模块化设计使得Arcana能适应从简单问答到复杂企业工作流的各种场景。实操心得在实现自定义步骤时务必遵循“纯函数”理念。步骤函数应该接收一个上下文返回一个新的上下文避免产生副作用。这保证了Pipeline的可测试性和可组合性。另外充分利用Arcana发出的Telemetry事件为你自定义的步骤也添加监控这对于后期调试和性能优化非常有帮助。5. 高级应用构建自主检索智能体Agentic LoopArcana.Loop代表了RAG演进的更高级形态。它不是执行一个预设的流程而是将“下一步做什么”的决策权交给了LLM控制器。这适用于那些无法预先确定检索步骤的开放性问题。5.1 Loop 的工作原理与配置一个典型的Loop使用场景如下# 1. 初始化一个Loop提出一个开放性问题 {:ok, ctx} Arcana.Loop.new( 找出《神秘博士》中所有博士的同伴最终背叛了他的剧集并简述背叛的原因。, repo: MyApp.Repo, collection: doctor-who, # 指定搜索的知识集合 max_iterations: 5 # 限制最大迭代次数防止无限循环 ) # 2. 运行Loop指定控制器和答案生成器模型 {:ok, final_ctx} Arcana.Loop.run(ctx, controller_llm: openai:gpt-4o-mini, # 负责决策的模型要求快、便宜 answer_llm: openai:gpt-4o # 负责撰写最终答案的模型可以更强、更贵 ) # 3. 分析结果 IO.puts(最终答案#{final_ctx.answer}) IO.puts(循环终止原因#{final_ctx.terminated_by}) # :answered, :gave_up, :max_iterations IO.inspect(final_ctx.tool_history) # 查看LLM调用工具的历史记录例如[:search, :search, :answer]Loop的内部状态机初始化创建初始上下文包含用户问题、可用工具集search,answer,give_up的定义、迭代计数器等。循环迭代 a. 将当前上下文包括历史对话、之前的检索结果格式化后发送给控制器LLM。 b. 控制器LLM根据理解决定调用哪个工具并生成符合工具调用格式的响应。 c. Loop执行被调用的工具 -search: 执行一次检索将结果以摘要形式加入上下文。 -answer: 控制器认为信息已足够触发答案生成器LLM基于所有累积的上下文生成面向用户的最终答案并终止循环。 -give_up: 控制器认为无法回答终止循环。 d. 更新迭代计数。如果达到max_iterations则触发回退合成直接用答案生成器LLM基于已收集的上下文生成一个答案然后终止。终止循环结束返回最终的上下文其中包含答案、工具调用历史和终止原因。5.2 控制器提示工程与工具定义Loop的性能高度依赖于控制器LLM的提示词System Prompt和工具定义。Arcana内置的提示词经过了精心设计但了解其原理有助于你进行微调。工具定义的精髓Anthropic关于“为智能体编写工具”的指南深深影响了Arcana的设计。工具描述不仅要说明“它能做什么”更要说明“什么时候不该用它”。例如search工具的描述会强调“仅当当前信息不足以直接回答问题且你认为进一步搜索可能找到相关信息时才使用。如果你已经拥有了回答问题所需的所有关键信息请使用answer工具。”双模型策略这是Loop模式的一个最佳实践。使用一个快速、廉价的模型如gpt-4o-mini,claude-3-haiku作为控制器因为它需要在多轮迭代中频繁被调用成本敏感。而最终答案的生成则交给一个更强大、更昂贵的模型如gpt-4o,claude-3-opus它只被调用一次用于产出高质量的回答。这样在效果和成本间取得了平衡。集合选择与锁定在Loop.new/2时你可以传入多个collections。控制器LLM在每次调用search工具时可以自主决定搜索哪个集合。这适用于跨领域知识库。如果你传入单个collection则工具定义中不会包含集合参数从而“锁定”搜索范围这是一种安全约束。5.3 实战案例多跳问答模拟假设我们有一个包含公司产品文档集合products和客户支持历史集合support的知识库。用户问“客户A反映的关于产品B的某个界面卡顿问题最后是怎么解决的”第一跳控制器LLM可能首先在products集合中搜索“产品B的界面卡顿常见原因”获取一些背景知识。第二跳基于初步信息它意识到需要具体的案例于是在support集合中搜索“客户A 产品B 卡顿”。第三跳检索到的支持记录提到了一个解决方案编号控制器可能再次在products或内部知识库如果存在中搜索该解决方案的详细步骤。最终回答控制器认为信息已完备调用answer工具由答案生成器综合所有信息生成给用户的答复。这个过程完全由LLM自主驱动无需开发者预先编写复杂的“如果-那么”规则。Loop的tool_history会清晰记录下[:search, :search, :search, :answer]这样的路径提供了可解释性。注意事项Agentic Loop虽然强大但也更不可预测且成本更高。务必设置max_iterations通常3-5轮足够来限制成本。同时密切监控tool_history和terminated_by如果发现大量循环以:gave_up或:max_iterations结束可能需要优化你的知识库内容、调整提示词或重新评估问题是否适合用Loop解决。对于有明确路径的问题使用Pipeline模式通常更高效、更可控。6. 知识图谱增强检索GraphRAG深入解析除了传统的向量检索Arcana还集成了GraphRAG能力通过构建和利用知识图谱来提升检索的深度和关联性。这尤其适合处理包含大量实体、关系以及需要深层推理的文档集。6.1 GraphRAG 的构建流程GraphRAG不是替代向量检索而是对其的增强。它的构建完全自动化发生在文档摄入阶段实体提取当文档被摄入时Arcana会使用一个NER命名实体识别模型通过Bumblebee扫描文本识别出如人物、组织、地点、产品、概念等实体。关系链接系统会分析句子结构尝试找出被提取实体之间的关系。例如在句子“张三在Acme公司开发了项目Alpha”中会建立“张三”-“工作于”-“Acme公司”和“张三”-“开发了”-“项目Alpha”的关系边。社区检测所有实体和关系构成一张大图。Arcana使用Leiden算法一种高效的社区发现算法对这张图进行聚类将紧密相关的实体分组形成“社区”。例如所有与“Phoenix框架”相关的实体如“LiveView”、“Channel”、“Ecto”可能会被分到同一个社区。社区摘要生成对于每个检测到的社区Arcana会使用LLM为该社区内的所有实体和关系生成一段连贯的文本摘要。这个摘要捕获了该社区的核心主题和内部关联。最终这些实体、关系、社区和社区摘要都被作为节点和边存入图数据库在Arcana中通过Ecto Schema存储在PostgreSQL中利用递归查询或扩展进行图遍历。6.2 图谱与向量的融合搜索当用户发起一个查询时Arcana可以执行“混合搜索”的增强版——向量、全文、图谱三重融合。向量与全文检索如前所述先进行标准的混合检索得到初始的相关文本块列表。图谱检索同时对查询进行实体提取。识别出的实体被用来在图谱中进行查找。实体节点检索直接找到与查询实体相关的节点。社区扩展检索找到这些实体所属的社区然后将整个社区的摘要文本作为额外的检索候选。这是GraphRAG的精华即使查询没有直接提到某个概念但如果这个概念与查询实体在同一个紧密社区内它也可能被检索到。这解决了“词汇不匹配”和“长尾关联”问题。结果融合将从图谱检索中得到的“社区摘要”文本块与向量/全文检索得到的文本块合并到一个候选池中。重排序最后使用交叉编码器对这个更大的候选池进行统一的重排序得出最终的最相关片段列表。这种融合方式对于复杂、多跳的查询尤其有效。例如查询“Elixir的创始人开发了哪些其他重要项目”。向量检索可能直接找到关于“Elixir创始人José Valim”的片段。而图谱检索通过“José Valim”节点关联到他所在的“Elixir生态”社区该社区的摘要可能提及“他也积极参与了Phoenix框架和Ecto库的早期开发”从而将“Phoenix”和“Ecto”作为相关信息检索出来即使原查询并未提及这两个词。6.3 配置与启用GraphRAGGraphRAG功能在Arcana中是可选的。要启用它你需要在配置中启动图谱存储和图构建服务并在摄入文档时开启相关选项。# 在 config/config.exs 中配置图谱服务 config :arcana, :graph_store, module: Arcana.GraphStore.Postgres # 使用PostgreSQL作为图存储 # 在 supervision tree 中启动图构建服务通常在 application.ex children [ # ... 其他服务 {Arcana.Graph.Builder, name: MyApp.GraphBuilder} ] # 在摄入文档时启用实体提取和图构建 {:ok, doc} Arcana.ingest(my_text_content, repo: MyApp.Repo, build_graph: true # 关键参数开启图谱构建 )启用后后续的搜索如果使用Arcana.search/2或Pipeline.search/1且没有显式禁用则会自动包含图谱融合的步骤。你也可以在Pipeline中精确控制ctx | Pipeline.search(fuse_with_graph: true) # 明确启用图谱融合 | ...性能考量构建知识图谱会增加文档摄入阶段的开销因为需要进行NER、关系提取和社区检测。对于大型文档集建议在后台异步执行Arcana路线图中的Async ingestion via Oban正是为此。在检索阶段图谱融合也会增加一些查询复杂度但通常带来的召回率提升是值得的。对于小型或领域狭窄的知识库如果实体关系不复杂可以评估是否真的需要GraphRAG。7. 评估、监控与问题排查构建RAG系统并非一劳永逸其效果需要持续评估和优化。Arcana提供了从指标评估到实时监控的完整工具链。7.1 构建评估体系如何知道你的RAG系统表现好坏你需要一个评估数据集和一套指标。创建测试集准备一组{问题 标准答案 相关文档ID}的元组。问题应覆盖你的常见查询类型。相关文档ID是“标准答案”所依据的源文档块用于计算检索指标。test_queries [ %{ query: Phoenix LiveView 是什么, reference_answer: 一个用于构建实时、服务器渲染Web UI的Elixir库..., relevant_chunk_ids: [chunk_123, chunk_456] # 这些ID来自你预先摄入的文档 }, # ... 更多测试用例 ]运行评估Arcana提供了Arcana.Evaluation模块来辅助自动化评估。results Enum.map(test_queries, fn test_case - {:ok, ctx} Arcana.ask(test_case.query, repo: Repo, llm: openai:gpt-4o-mini) %{ query: test_case.query, retrieved_ids: Enum.map(ctx.search_results, 1.chunk_id), # 实际检索到的ID answer: ctx.answer, reference_answer: test_case.reference_answer, relevant_ids: test_case.relevant_chunk_ids } end)计算关键指标检索阶段指标召回率 (RecallK)在前K个检索结果中包含了多少比例的标准相关文档。Recall1和Recall5是常用指标。平均倒数排名 (MRR)对所有问题计算标准答案第一次出现的位置的倒数然后取平均。这个指标对排名靠前的结果更敏感。生成阶段指标忠实度 (Faithfulness)使用Pipeline.ground/2或类似NLI模型计算生成的答案在多大程度上忠实于检索到的上下文而非“幻觉”。答案相关性 (Answer Relevance)评估生成的答案是否直接回答了问题。这通常需要LLM-as-a-judge或人工评估。Arcana的Dashboard内置了运行评估任务和可视化这些指标的基础功能。7.2 利用Telemetry进行监控Arcana深度集成了Elixir的:telemetry库。几乎所有重要操作都会发出事件让你可以实时监控系统健康状态和性能。关键事件示例[:arcana, :embedder, :encode, :start]/[:arcana, :embedder, :encode, :stop]嵌入模型调用耗时。[:arcana, :search, :start]/[:arcana, :search, :stop]单次搜索总耗时。[:arcana, :pipeline, :step, :start]/[:arcana, :pipeline, :step, :stop]每个Pipeline步骤的耗时附有步骤名。[:arcana, :llm, :call, :start]/[:arcana, :llm, :call, :stop]每次LLM API调用的耗时和令牌使用情况。你可以将这些事件接入你的监控系统如LiveDashboard、Telemetry.Metrics Prometheus Grafana。# 示例在应用启动时附加一个简单的日志处理器 :telemetry.attach( arcana-logger, [:arcana, :search, :stop], fn _event_name, measurements, _metadata, _config - IO.inspect(Search completed in #{measurements.duration}ms) end, nil )7.3 常见问题与排查技巧问题1检索结果不相关检查嵌入模型你使用的嵌入模型是否与你的文档领域匹配通用模型在处理高度专业术语时可能效果不佳。考虑使用领域内微调的模型或尝试Arcana支持的E5系列模型它们支持在查询前添加指令前缀。调整分块策略默认分块大小和重叠可能不适合你的文档。Arcana的Chunker是可配置的。对于技术文档较小的块如256字符可能更好对于叙事性内容较大的块可能更合适。优化混合搜索权重Arcana.search/2默认对向量和全文搜索结果进行RRF融合。你可以调整两者的权重vector_weight和fulltext_weight如果你的文档关键词特征明显可以适当提高全文搜索的权重。问题2LLM生成的答案出现“幻觉”启用并检查Grounding步骤确保在Pipeline中包含了Pipeline.ground/2步骤并监控其输出的grounding.score。如果分数持续偏低说明检索到的上下文不足以支撑生成或者LLM的指令需要加强。优化提示词Arcana的answer步骤有默认的提示词但你可以在调用Pipeline.answer/2时传入自定义的prompt或prompt_fn。在提示词中强烈要求模型“严格基于提供的上下文回答如果上下文没有相关信息就说不知道”。增加检索数量尝试增加search步骤返回的候选数量top_k参数为重排序和生成提供更多素材。问题3系统响应慢定位瓶颈使用Telemetry数据。是嵌入慢检索慢还是LLM调用慢嵌入慢可以尝试启用GPUEXLA或使用更小的模型。检索慢可以检查数据库索引确保embedding向量列有ivfflat或hnsw索引。LLM调用慢可以考虑使用更快的模型或为API调用设置合理的超时和重试。启用缓存对于频繁出现的相同或相似查询可以考虑在应用层实现一个简单的缓存缓存查询向量 - 检索结果的映射。异步处理对于文档摄入等后台任务务必使用异步作业如Oban避免阻塞实时请求。问题4Agentic Loop陷入无限循环或无效搜索审查工具调用历史查看ctx.tool_history。如果看到大量连续的search而无answer可能是控制器LLM无法从搜索结果中合成答案。优化控制器提示词确保工具描述清晰特别是“何时停止搜索”的规则。可以尝试在系统提示中强调“如果你在连续两次搜索后没有得到新的关键信息你应该考虑使用answer或give_up”。提供更好的搜索结果摘要Arcana在给控制器LLM反馈搜索结果时不是返回原始文本块而是生成一个简洁的摘要。确保这个摘要信息量足够能帮助LLM判断价值。Arcana将强大的RAG能力无缝地带入了Elixir和Phoenix的世界。它从设计上就拥抱了BEAM平台的特性——并发、容错、内置可观测性让你能用熟悉的工具和范式构建智能应用。无论是通过简单的ask/2快速上线一个问答机器人还是利用Pipeline构建复杂的文档处理流程或是探索前沿的Loop实现自主检索智能体Arcana都提供了坚实且灵活的基础。更重要的是它坚持“本地优先”和“一体化”的理念在追求功能强大的同时也极大地简化了运维和降低了长期成本。对于任何希望在其Elixir应用中深度集成智能检索与生成能力的团队来说Arcana都是一个值得深入研究和采用的关键库。