如果你被一堆“文档太多、答案全靠搜”的项目缠住那你大概率已经在评估 RAG 了。用Phidata PgVector搭一个智能检索问答助手是我最近在多个内部工具型项目里反复用过、也踩过不少坑之后觉得最值得推荐的一条路线。它不像从零写那一套加载、切块、入向量库、召回、再喂给模型的流程那么繁琐也不像某些重框架那样上了就得买全家桶。Phidata 天然把 Agent、知识库、记忆、工具调用串在一起PgVector 则让原本很重的一套向量基础设施直接塞进你已经在用的 PostgreSQL 里运维和心理负担都小很多。这篇文章我会从最基础的原理讲起手把手带你走一遍环境准备、文档加载、Agent 问答、记忆与工具扩展、生产环境调优再到常见问题排查。不管你之前有没有接触过 RAG跟着这套思路走应该都能在一天内把第一个能回答专业文档问题的助手跑起来。如果你已经是老手重点看第 4 节和第 5 节那里面有一部分是我在调检索质量和处理并发时总结的实操心得。1. 先想清楚RAG 助手的本质是什么为什么这套组合合适1.1 RAG 不是简单的“向量搜索 大模型”很多人把 RAG 想得太简单以为就是把问题拿去搜一搜、再把搜到的内容拼到 Prompt 里。实际上一个完整的 RAG 链路至少包含文档加载、文本切块、向量化、向量存储、检索召回、上下文组织、生成回答。任何一个环节做得糙最终答案都会翻车。举个例子假设你要做一个“产品说明书问答助手”。用户问“发票丢了还能保修吗”如果只是按关键词搜系统可能把“保修条款”“发票要求”两个片段割裂地搜出来然后模型拼出一句“可以保修”但没提示需要什么凭证。真正合格的 RAG 要能把“保修需要发票”“发票丢失可提供购买记录”两段上下文都召回再让模型给出有条件的回答。这要求的不只是向量数据库跑得通更是分块粒度、召回数量、Prompt 结构之间的配合。Phidata 聪明的地方在于它没有把 RAG 拆成一堆必须自己拼装的零件而是把“知识库 向量库 Agent”作为一等公民封装好了。你关心的不是“这一步调哪个接口”而是“我的 Agent 应该怎么回答问题”。这种思维方式的转变对后期维护和功能扩展帮助非常大。1.2 Phidata 的价值从“检索脚本”到“Agent”的跨越Phidata 最早出圈是因为做 Agent 开发很顺手后来它的知识库抽象也越来越成熟。核心组件大概是这几块Agent对话主体负责理解用户输入、决定要不要查知识库、组织回答。KnowledgeBase统一管理文档的加载、分块、嵌入、重载逻辑。VectorDB检索后端接口PgVector、专用向量库、内存向量库都可以接。Memory短期会话记忆和长期用户记忆能存到 Postgres 里。用这套抽象代码写起来非常符合直觉。我这里说的是它的真实用法不是概念预期。以我最早接触的早期版本为例环境变量、命令名、类名都改过好几次所以你看文档时如果发现某个模块路径和网上文章对不上别慌以你装的那个版本的官方示例为准。Phidata 的快速迭代是它活跃的体现但也确实坑了一批照抄老教程的人。1.3 为什么用 PgVector 而不是一个独立向量库市面上的向量数据库不少各有各的优点。但落到企业内部的“文档问答助手”这种场景我越来越倾向于 PgVector理由很实在运维简单大多数团队已经有 PostgreSQL再往里面装一个扩展比单独维护一套 Milvus 或 Weaviate 轻量太多。事务与备份业务数据、用户对话记录、向量数据放同一套数据库可以用统一的备份、权限、审计机制。分开两套系统备份恢复也不得不同时考虑两边。元数据过滤方便向量检索时经常要按文档类型、部门、时间范围过滤PostgreSQL 的常规字段和向量索引可以写在同一条 SQL 里不用在业务代码里做两段式拼接。数据量适中够用对“几十万篇文档”“百万级 chunk”这个量级PgVector 配合 HNSW 索引完全能扛住。真正到了亿级向量再迁移也不迟没必要一开始就上重型武器。2. 环境准备把 Phidata 和 PgVector 跑起来2.1 安装依赖并准备 PostgreSQL在开始之前先确认你的机器上有 Python 3.9 以上版本。我建议直接建一个干净的虚拟环境避免跟系统 Python 或其他项目的包互相污染。# 创建并激活虚拟环境 python3 -m venv .rag-env source .rag-env/bin/activate # 安装 Phidata pip install -U phidata接下来要解决 PostgreSQL。如果你本地本来就有只需要确认版本在 14 以上因为 pgvector 对新版本支持更平滑。如果没有我个人最省事的方式是用 Docker 起一个带 pgvector 的实例docker run -d \ --name pg-rag \ -e POSTGRES_USERai \ -e POSTGRES_PASSWORDai \ -e POSTGRES_DBai \ -p 5532:5432 \ pgvector/pgvector:pg16这里把宿主机端口映射到 5532是为了避免和本机已有的 PostgreSQL 冲突。如果你本机没有装过 PostgreSQL直接映射 5432 也没问题。启动后建议用 psql 验证一下扩展docker exec -it pg-rag psql -U ai -d ai -c CREATE EXTENSION IF NOT EXISTS vector;如果你用的是自己安装的 PostgreSQL也一定要先执行这条CREATE EXTENSION否则后续建表会直接报“type vector does not exist”。2.2 设计数据库连接串Phidata 内部的 PgVector 通过 SQLAlchemy 连接 PostgreSQL连接串格式一般是DB_URL postgresqlpsycopg://ai:ailocalhost:5532/ai拆开来看postgresqlpsycopg表示用 psycopg 驱动后面的ai:ailocalhost:5532/ai就是用户名、密码、地址、端口、数据库名。我用的是 psycopg因为 Phidata 在当前版本里对它的支持最顺比 psycopg2 和 asyncpg 少一些序列化方面的小问题。你要是遇到驱动缺失先跑一句pip install psycopg[binary]。连接串里的信息不是死的端口、密码改成你自己的即可。测试连接最快的方法不是写 Python而是用 psql 连一下PGPASSWORDai psql -h localhost -p 5532 -U ai -d ai -c SELECT 1能返回 1说明连接没问题。这一步值得做因为过后你分不清到底是代码问题还是数据库没起来。2.3 准备第一批文档环境就绪后需要一个测试文档。最方便的是一份 PDF任何产品手册、内部制度文件都行。如果没有现成的也可以先准备一份 txt 或 markdown 文件这样后面验证代码时不用等待太久的格式解析。我自己通常更喜欢用本地文件起步因为加载流程可控不会像 URL 加载那样受到网络、超时、页面结构变化的影响。把这份文档放在项目目录下的data/目录命名为manual.pdf后面代码直接指向它。3. 实现核心让助手针对文档回答问题3.1 用 Phidata 加载知识库并构建检索型 Agent这是整套方案里最关键的一步。下面这段代码是能跑起来的最简形态from phi.agent import Agent from phi.knowledge.pdf import PDFKnowledgeBase from phi.vectordb.pgvector import PgVector DB_URL postgresqlpsycopg://ai:ailocalhost:5532/ai # 1. 定义知识库本地 PDF PgVector 作为向量检索后端 knowledge_base PDFKnowledgeBase( pathdata/manual.pdf, vector_dbPgVector(table_namepdf_documents, db_urlDB_URL), ) # 2. 首次运行时加载文档之后注释掉这行 knowledge_base.load(recreateTrue)load(recreateTrue)的意思是重新加载文档、重新切块、重新生成向量并把表结构重建。第一次运行时用recreateTrue很合适因为表还不存在。但之后每次加载都recreateTrue会导致全量重建如果文档没变化建议改成knowledge_base.load()这样可以基于主键去重更新节省大量时间。加载完成后再来定义 Agent 本体agent Agent( modelOllama(idqwen2.5:7b), knowledge_baseknowledge_base, search_knowledgeTrue, add_referencesTrue, instructions[ 你是企业内部文档顾问只能依据用户提供的文档回答。, 如果知识库中没有明确答案直接告诉用户不清楚不要编造。, 回答时要引用文档中对应的条款或页码。, ], )search_knowledgeTrue是让 Agent 在收到用户问题后先去知识库检索add_referencesTrue是在回答里附上来源片段这个对排查幻觉非常有帮助。注意上面我用了Ollama作为模型来源这是另一个开源工具负责在本地跑开源模型不需要联网调云服务。关于模型这块我在下一节展开说明。3.2 模型选型本地模型还是云端模型RAG 助手除了检索还需要生成回答这一步依赖大模型。如果你是个人学习或者数据敏感我建议先用 Ollama 跑本地开源模型做验证。安装 Ollama 后拉取一个模型ollama pull qwen2.5:7b ollama pull nomic-embed-text然后回到 Python模型部分这样写from phi.model.ollama import Ollama agent Agent( modelOllama(idqwen2.5:7b), ... )嵌入模型也要单独指定保证 Phidata 在用同一个模型做向量化from phi.embedder.ollama import OllamaEmbedder knowledge_base PDFKnowledgeBase( pathdata/manual.pdf, vector_dbPgVector(table_namepdf_documents, db_urlDB_URL), embedderOllamaEmbedder(modelnomic-embed-text, dimensions768), )dimensions必须和嵌入模型输出的向量维度一致。不同的嵌入模型维度可能完全不同比如有的是 768 维有的是 1024 维、1536 维。如果换成另一个嵌入模型但维度还写 768启动时就可能报向量维度不一致的错误。如果你所在环境允许使用云端模型 API只要把Ollama替换成对应厂商在 Phidata 里的模型类即可其余代码不用动。这也是 Phidata 的一个好处模型层完全隔离业务代码不需要大规模修改。3.3 运行并验证第一个 RAG 问答把上面代码保存为agent.py直接运行python agent.py如果一切正常Phidata 会启动一个交互式会话。这时你就可以在控制台里提问了。我刚才那个“发票丢了还能保修吗”就是很好的测试问题。第一次跑可能有点慢因为本地模型要加载到内存。耐心等一下回答质量会随着后续提问逐渐稳定下来。除了控制台Phidata 还提供了一套基于 Streamlit 的界面。如果你只想快速可视化可以再装一个 Streamlitpip install streamlit然后在代码里加几行把 Agent 暴露成 Web 聊天界面。这一步对非技术同事验收特别有效大家能直观看到这个助手真的能回答问题。我个人建议尽早让业务同事参与测试因为他们提出的真实问题往往比你自己脑补的测试问题更能暴露知识库的盲点。4. 进阶给助手加记忆和工具从问答走向 Agent4.1 用 PgMemoryDb 实现会话记忆与长期记忆第一个版本能回答问题但从产品角度看还不够因为每次会话都是独立的。用户上一轮说了“我是华东区的”下一轮问“我们区的保修政策是什么”Agent 应该记得“华东区”这个上下文。这就要给 Agent 加记忆能力。Phidata 里有专门的 Memory 抽象而且可以接同一个 PostgreSQLfrom phi.memory.db.postgres import PgMemoryDb agent Agent( modelOllama(idqwen2.5:7b), knowledge_baseknowledge_base, search_knowledgeTrue, add_referencesTrue, memory_dbPgMemoryDb(table_nameagent_memory, db_urlDB_URL), add_history_to_messagesTrue, )add_history_to_messagesTrue会在每次请求时把历史消息一起带给模型实现多轮对话的连贯性。同时PgMemoryDb把会话记录写入 PostgreSQL重启应用后记忆还在。这比内存存储可靠得多也是我一直强调“用同一套数据库”的原因业务数据、向量、记忆全在一个地方备份一次搞定。4.2 通过工具调用扩展 Agent 的边界RAG 解决的是“从文档里找答案”但很多业务场景不只有文档。比如用户问“现在几点”“帮我算一下这批货的总价”这些都不在文档里Agent 需要调用外部函数。Phidata 的 Agent 支持把 Python 函数直接注册为工具。我举个简单例子。假设你要让助手能根据文档内容 当前时间给出更准确的答复可以这样from datetime import datetime def get_current_time(): 返回当前服务器时间格式为 YYYY-MM-DD HH:MM:SS return datetime.now().strftime(%Y-%m-%d %H:%M:%S) agent Agent( modelOllama(idqwen2.5:7b), knowledge_baseknowledge_base, search_knowledgeTrue, tools[get_current_time], show_tool_callsTrue, )show_tool_callsTrue会把模型决定调用哪个函数的过程显示出来。这非常有用因为它暴露了模型的内在推理链路。如果你发现模型什么问题都先去调函数、而不是先查知识库说明 Prompt 里的工具使用说明需要调整或者工具描述写得太宽泛了。工具调用的本质是把“检索文档”和“执行计算”这两件不同的事分开文档检索走知识库实时信息走函数。这样职责清晰后期也容易加权限控制比如某些函数只允许特定角色调用。4.3 多 Agent 分工把问题拆解得更细单 Agent 能处理不少任务但碰到复杂业务一个 Agent 包打天下会越来越笨拙。Phidata 支持把多个 Agent 组合成 Team不同 Agent 负责不同专业领域。举个例子假设知识库里有产品手册也有售后政策。你可以建两个 Agent产品Agent专注回答产品参数、使用方法。售后Agent专注保修、退换货政策。再建一个“调度 Agent”负责理解用户问题、决定转发给哪个子 Agent、最后汇总结果。这种架构的好处是每个 Agent 的知识库更聚焦Prompt 也更短回答质量更稳定。代价是系统复杂度上升不建议第一版就上先让单个 Agent 把主流程跑通再说。5. 生产环境调优检索质量与稳定性5.1 分块参数chunk_size 与 overlap 怎么调RAG 回答质量很大程度上取决于文本分块。分块太粗一段里混了多个主题检索时召回的内容不聚焦分块太细语义被切碎模型拿到的上下文支离破碎。Phidata 默认加载文档后会把文本切分成小块常见的默认值大约在 300 字符左右、重叠 60 字符左右。我实际用下来的经验如下文档类型建议 chunk_size建议 overlap理由产品手册/制度文件300-50050-80条款相对独立保留些上下文即可论文/长叙述文档500-80080-120语义跨度大需要更长上下文对话/FAQ200-30020-40QA 结构紧凑分块太大会混入无关Q你可以用一个小脚本打印切块后的片段直观感受分块效果。如果看到一块里混杂了两个完全无关的主题就该调小 chunk_size如果发现一个完整的答案被拦腰截断就该调大 chunk_size 或增加 overlap。5.2 向量索引HNSW 与参数调优PgVector 支持两种索引IVFFlat 和 HNSW。IVFFlat 需要先有足够数据才能建索引而且要指定聚类中心数量不够灵活。HNSW 则是一种近似最近邻的图索引查询速度快构建参数相对少更适合大多数应用场景。建索引的 SQL 大概是这样的CREATE INDEX ON pdf_documents USING hnsw (embedding vector_cosine_ops);分片是 Phidata 自动建的但索引策略可以自己控制。如果你发现检索变慢或者召回质量下降可以先检查索引是否生效EXPLAIN ANALYZE SELECT * FROM pdf_documents ORDER BY embedding [向量] LIMIT 10;注意vector_cosine_ops是针对余弦距离的操作符类如果你用的是欧氏距离要换成vector_l2_ops。Phidata 默认的检索方式通常与余弦距离保持一致所以一般用vector_cosine_ops就行。5.3 数据库连接与并发处理上线之后多个用户同时提问每个问题都会触发知识库检索PostgreSQL 连接数可能瞬间被打爆。SQLAlchemy 的连接池默认值不一定够用建议根据并发量调整。Phidata 的 PgVector 底层使用 SQLAlchemy所以在连接串里加查询参数可以控制连接池大小DB_URL postgresqlpsycopg://ai:ailocalhost:5532/ai?pool_size10max_overflow20pool_size10表示保持 10 个连接max_overflow20表示高峰时可以临时扩充到 30。如果你的机器资源有限这个数字不要调太大否则连接风暴会反过来拖垮数据库。还有一点容易被忽略定期重载知识库。文档更新后旧向量还留在表里不重载的话检索到的可能是过期内容。你可以写一个定时任务在凌晨低峰期调用knowledge_base.load()用增量更新方式同步变化。配合日志记录哪天回答出错了也能清楚到底是哪份文档里的旧内容导致的问题。6. 常见问题与排查技巧实录6.1 加载文档之后检索结果总为空这是新手最容易遇到的问题。可能的原因有三个表和索引没建成功检查pdf_documents表是否真的存在SELECT COUNT(*) FROM pdf_documents;看有没有数据。向量化失败如果 embedding 模型没配好加载时不会报错但库里全是空向量。查看加载日志出现 embedding 相关警告就说明有问题。检索条件过于严格用户的提问方式和文档原文差异太大。先搜一个文档里的原文片段如果原文都搜不到那一定是链路问题如果原文能搜到说明又是语义匹配的调优问题。6.2 更换 embedding 模型后维度不一致之前说过不同 embedding 模型输出的向量维度不同。如果你之前用的是 768 维后来换成了 1024 维的模型直接跑会报维度错误。这时需要把对应表删掉重建或者先TRUNCATE再重新load(recreateTrue)。更稳妥的做法是从第一天起就把 embedding 模型固定下来不要在生产环境频繁切换。升级模型前先在测试环境完整验证一轮确认检索质量确实提升了再动手。6.3 回答不引用文档感觉像在瞎编我在第 3 节提到add_referencesTrue这一步只是把来源附在回答里但 Prompt 里的 Instructions 才是决定模型“要不要引用文档”的关键。我在项目里经常给 Agent 加这样一条当你引用文档内容时必须标明来源文件的名称和对应章节。 如果用户问你一个你无法从文档中确认的问题请回答“该问题在现有文档中未找到明确说明”。这样能大幅减少幻觉。你还可以在 Agent 里打开详细日志把检索到的片段打印出来确认模型到底看了哪些内容。很多时候回答不准不是模型不行而是检索回来的内容里确实没有正确答案。6.4 PostgreSQL 权限不足无法创建扩展Docker 方式启动的 PostgreSQL 一般没问题但你用已有实例时可能遇到当前用户没有超级权限导致CREATE EXTENSION vector失败。解决方法是切换到超级用户或者让管理员先创建好扩展再给业务用户授权。不要在一个共享数据库里用超级用户跑日常业务那是运维事故的温床。6.5 我踩过几次坑之后想分享几个心得第一知识库的内容质量比模型大小重要得多。我见过有人换了更大的模型回答反而变差了原因就是文档本身过时、矛盾、格式混乱。先把文档整理干净比换模型更划算。第二先小步验证再扩大规模。不要第一天就把一百份文档全塞进去先拿一份文档打通链路确认每一个环节都正常再逐步加文档。全量加载之后如果回答质量下降你也知道是新加的哪批文档出了问题。第三把检索日志当成产品监控来做。每次问答都记录一下“检索了哪些片段、命中了哪份文档、得分是多少”。有了这些日志用户反馈“回答不对”时你能快速定位是检索没召回还是模型没理解。这一步在早期省了我大量时间。第四注意知识库的权限边界。企业内部文档常常混杂着公开信息和敏感内容向量检索本身不会区分权限。如果系统要给不同角色开放不同范围的知识库一定要在应用层做好文档级别的访问控制不要让向量表裸奔在公网环境。最后的一点个人体会这套 Phidata PgVector 的组合我最喜欢的地方是它没有逼着你把技术栈拆得七零八落。一个 Python 环境、一个 PostgreSQL 实例就能把一个智能问答助手从原型带到生产。比起那些动辄要部署三四个服务的方案这套简化掉的运维复杂度会变成你后续迭代的信心来源。我在实际使用中最大的感受是RAG 的技术门槛没那么高真正难的是把检索质量调稳、把知识库内容管好以及让 Agent 在“知道”和“不知道”之间诚实切换。如果你正要开始做智能 RAG 助手不妨先按这篇文章跑通最小闭环再根据你自己的文档特点去调整分块和检索参数。接下来你还可以往多模态文档、结构化知识图谱、自动知识库更新这些方向去扩展每一步都有 Phidata 的组件在背后撑着不会让你推倒重来。 Phidata + PgVector 构建企业级 RAG 智能问答助手实战
如果你被一堆“文档太多、答案全靠搜”的项目缠住那你大概率已经在评估 RAG 了。用Phidata PgVector搭一个智能检索问答助手是我最近在多个内部工具型项目里反复用过、也踩过不少坑之后觉得最值得推荐的一条路线。它不像从零写那一套加载、切块、入向量库、召回、再喂给模型的流程那么繁琐也不像某些重框架那样上了就得买全家桶。Phidata 天然把 Agent、知识库、记忆、工具调用串在一起PgVector 则让原本很重的一套向量基础设施直接塞进你已经在用的 PostgreSQL 里运维和心理负担都小很多。这篇文章我会从最基础的原理讲起手把手带你走一遍环境准备、文档加载、Agent 问答、记忆与工具扩展、生产环境调优再到常见问题排查。不管你之前有没有接触过 RAG跟着这套思路走应该都能在一天内把第一个能回答专业文档问题的助手跑起来。如果你已经是老手重点看第 4 节和第 5 节那里面有一部分是我在调检索质量和处理并发时总结的实操心得。1. 先想清楚RAG 助手的本质是什么为什么这套组合合适1.1 RAG 不是简单的“向量搜索 大模型”很多人把 RAG 想得太简单以为就是把问题拿去搜一搜、再把搜到的内容拼到 Prompt 里。实际上一个完整的 RAG 链路至少包含文档加载、文本切块、向量化、向量存储、检索召回、上下文组织、生成回答。任何一个环节做得糙最终答案都会翻车。举个例子假设你要做一个“产品说明书问答助手”。用户问“发票丢了还能保修吗”如果只是按关键词搜系统可能把“保修条款”“发票要求”两个片段割裂地搜出来然后模型拼出一句“可以保修”但没提示需要什么凭证。真正合格的 RAG 要能把“保修需要发票”“发票丢失可提供购买记录”两段上下文都召回再让模型给出有条件的回答。这要求的不只是向量数据库跑得通更是分块粒度、召回数量、Prompt 结构之间的配合。Phidata 聪明的地方在于它没有把 RAG 拆成一堆必须自己拼装的零件而是把“知识库 向量库 Agent”作为一等公民封装好了。你关心的不是“这一步调哪个接口”而是“我的 Agent 应该怎么回答问题”。这种思维方式的转变对后期维护和功能扩展帮助非常大。1.2 Phidata 的价值从“检索脚本”到“Agent”的跨越Phidata 最早出圈是因为做 Agent 开发很顺手后来它的知识库抽象也越来越成熟。核心组件大概是这几块Agent对话主体负责理解用户输入、决定要不要查知识库、组织回答。KnowledgeBase统一管理文档的加载、分块、嵌入、重载逻辑。VectorDB检索后端接口PgVector、专用向量库、内存向量库都可以接。Memory短期会话记忆和长期用户记忆能存到 Postgres 里。用这套抽象代码写起来非常符合直觉。我这里说的是它的真实用法不是概念预期。以我最早接触的早期版本为例环境变量、命令名、类名都改过好几次所以你看文档时如果发现某个模块路径和网上文章对不上别慌以你装的那个版本的官方示例为准。Phidata 的快速迭代是它活跃的体现但也确实坑了一批照抄老教程的人。1.3 为什么用 PgVector 而不是一个独立向量库市面上的向量数据库不少各有各的优点。但落到企业内部的“文档问答助手”这种场景我越来越倾向于 PgVector理由很实在运维简单大多数团队已经有 PostgreSQL再往里面装一个扩展比单独维护一套 Milvus 或 Weaviate 轻量太多。事务与备份业务数据、用户对话记录、向量数据放同一套数据库可以用统一的备份、权限、审计机制。分开两套系统备份恢复也不得不同时考虑两边。元数据过滤方便向量检索时经常要按文档类型、部门、时间范围过滤PostgreSQL 的常规字段和向量索引可以写在同一条 SQL 里不用在业务代码里做两段式拼接。数据量适中够用对“几十万篇文档”“百万级 chunk”这个量级PgVector 配合 HNSW 索引完全能扛住。真正到了亿级向量再迁移也不迟没必要一开始就上重型武器。2. 环境准备把 Phidata 和 PgVector 跑起来2.1 安装依赖并准备 PostgreSQL在开始之前先确认你的机器上有 Python 3.9 以上版本。我建议直接建一个干净的虚拟环境避免跟系统 Python 或其他项目的包互相污染。# 创建并激活虚拟环境 python3 -m venv .rag-env source .rag-env/bin/activate # 安装 Phidata pip install -U phidata接下来要解决 PostgreSQL。如果你本地本来就有只需要确认版本在 14 以上因为 pgvector 对新版本支持更平滑。如果没有我个人最省事的方式是用 Docker 起一个带 pgvector 的实例docker run -d \ --name pg-rag \ -e POSTGRES_USERai \ -e POSTGRES_PASSWORDai \ -e POSTGRES_DBai \ -p 5532:5432 \ pgvector/pgvector:pg16这里把宿主机端口映射到 5532是为了避免和本机已有的 PostgreSQL 冲突。如果你本机没有装过 PostgreSQL直接映射 5432 也没问题。启动后建议用 psql 验证一下扩展docker exec -it pg-rag psql -U ai -d ai -c CREATE EXTENSION IF NOT EXISTS vector;如果你用的是自己安装的 PostgreSQL也一定要先执行这条CREATE EXTENSION否则后续建表会直接报“type vector does not exist”。2.2 设计数据库连接串Phidata 内部的 PgVector 通过 SQLAlchemy 连接 PostgreSQL连接串格式一般是DB_URL postgresqlpsycopg://ai:ailocalhost:5532/ai拆开来看postgresqlpsycopg表示用 psycopg 驱动后面的ai:ailocalhost:5532/ai就是用户名、密码、地址、端口、数据库名。我用的是 psycopg因为 Phidata 在当前版本里对它的支持最顺比 psycopg2 和 asyncpg 少一些序列化方面的小问题。你要是遇到驱动缺失先跑一句pip install psycopg[binary]。连接串里的信息不是死的端口、密码改成你自己的即可。测试连接最快的方法不是写 Python而是用 psql 连一下PGPASSWORDai psql -h localhost -p 5532 -U ai -d ai -c SELECT 1能返回 1说明连接没问题。这一步值得做因为过后你分不清到底是代码问题还是数据库没起来。2.3 准备第一批文档环境就绪后需要一个测试文档。最方便的是一份 PDF任何产品手册、内部制度文件都行。如果没有现成的也可以先准备一份 txt 或 markdown 文件这样后面验证代码时不用等待太久的格式解析。我自己通常更喜欢用本地文件起步因为加载流程可控不会像 URL 加载那样受到网络、超时、页面结构变化的影响。把这份文档放在项目目录下的data/目录命名为manual.pdf后面代码直接指向它。3. 实现核心让助手针对文档回答问题3.1 用 Phidata 加载知识库并构建检索型 Agent这是整套方案里最关键的一步。下面这段代码是能跑起来的最简形态from phi.agent import Agent from phi.knowledge.pdf import PDFKnowledgeBase from phi.vectordb.pgvector import PgVector DB_URL postgresqlpsycopg://ai:ailocalhost:5532/ai # 1. 定义知识库本地 PDF PgVector 作为向量检索后端 knowledge_base PDFKnowledgeBase( pathdata/manual.pdf, vector_dbPgVector(table_namepdf_documents, db_urlDB_URL), ) # 2. 首次运行时加载文档之后注释掉这行 knowledge_base.load(recreateTrue)load(recreateTrue)的意思是重新加载文档、重新切块、重新生成向量并把表结构重建。第一次运行时用recreateTrue很合适因为表还不存在。但之后每次加载都recreateTrue会导致全量重建如果文档没变化建议改成knowledge_base.load()这样可以基于主键去重更新节省大量时间。加载完成后再来定义 Agent 本体agent Agent( modelOllama(idqwen2.5:7b), knowledge_baseknowledge_base, search_knowledgeTrue, add_referencesTrue, instructions[ 你是企业内部文档顾问只能依据用户提供的文档回答。, 如果知识库中没有明确答案直接告诉用户不清楚不要编造。, 回答时要引用文档中对应的条款或页码。, ], )search_knowledgeTrue是让 Agent 在收到用户问题后先去知识库检索add_referencesTrue是在回答里附上来源片段这个对排查幻觉非常有帮助。注意上面我用了Ollama作为模型来源这是另一个开源工具负责在本地跑开源模型不需要联网调云服务。关于模型这块我在下一节展开说明。3.2 模型选型本地模型还是云端模型RAG 助手除了检索还需要生成回答这一步依赖大模型。如果你是个人学习或者数据敏感我建议先用 Ollama 跑本地开源模型做验证。安装 Ollama 后拉取一个模型ollama pull qwen2.5:7b ollama pull nomic-embed-text然后回到 Python模型部分这样写from phi.model.ollama import Ollama agent Agent( modelOllama(idqwen2.5:7b), ... )嵌入模型也要单独指定保证 Phidata 在用同一个模型做向量化from phi.embedder.ollama import OllamaEmbedder knowledge_base PDFKnowledgeBase( pathdata/manual.pdf, vector_dbPgVector(table_namepdf_documents, db_urlDB_URL), embedderOllamaEmbedder(modelnomic-embed-text, dimensions768), )dimensions必须和嵌入模型输出的向量维度一致。不同的嵌入模型维度可能完全不同比如有的是 768 维有的是 1024 维、1536 维。如果换成另一个嵌入模型但维度还写 768启动时就可能报向量维度不一致的错误。如果你所在环境允许使用云端模型 API只要把Ollama替换成对应厂商在 Phidata 里的模型类即可其余代码不用动。这也是 Phidata 的一个好处模型层完全隔离业务代码不需要大规模修改。3.3 运行并验证第一个 RAG 问答把上面代码保存为agent.py直接运行python agent.py如果一切正常Phidata 会启动一个交互式会话。这时你就可以在控制台里提问了。我刚才那个“发票丢了还能保修吗”就是很好的测试问题。第一次跑可能有点慢因为本地模型要加载到内存。耐心等一下回答质量会随着后续提问逐渐稳定下来。除了控制台Phidata 还提供了一套基于 Streamlit 的界面。如果你只想快速可视化可以再装一个 Streamlitpip install streamlit然后在代码里加几行把 Agent 暴露成 Web 聊天界面。这一步对非技术同事验收特别有效大家能直观看到这个助手真的能回答问题。我个人建议尽早让业务同事参与测试因为他们提出的真实问题往往比你自己脑补的测试问题更能暴露知识库的盲点。4. 进阶给助手加记忆和工具从问答走向 Agent4.1 用 PgMemoryDb 实现会话记忆与长期记忆第一个版本能回答问题但从产品角度看还不够因为每次会话都是独立的。用户上一轮说了“我是华东区的”下一轮问“我们区的保修政策是什么”Agent 应该记得“华东区”这个上下文。这就要给 Agent 加记忆能力。Phidata 里有专门的 Memory 抽象而且可以接同一个 PostgreSQLfrom phi.memory.db.postgres import PgMemoryDb agent Agent( modelOllama(idqwen2.5:7b), knowledge_baseknowledge_base, search_knowledgeTrue, add_referencesTrue, memory_dbPgMemoryDb(table_nameagent_memory, db_urlDB_URL), add_history_to_messagesTrue, )add_history_to_messagesTrue会在每次请求时把历史消息一起带给模型实现多轮对话的连贯性。同时PgMemoryDb把会话记录写入 PostgreSQL重启应用后记忆还在。这比内存存储可靠得多也是我一直强调“用同一套数据库”的原因业务数据、向量、记忆全在一个地方备份一次搞定。4.2 通过工具调用扩展 Agent 的边界RAG 解决的是“从文档里找答案”但很多业务场景不只有文档。比如用户问“现在几点”“帮我算一下这批货的总价”这些都不在文档里Agent 需要调用外部函数。Phidata 的 Agent 支持把 Python 函数直接注册为工具。我举个简单例子。假设你要让助手能根据文档内容 当前时间给出更准确的答复可以这样from datetime import datetime def get_current_time(): 返回当前服务器时间格式为 YYYY-MM-DD HH:MM:SS return datetime.now().strftime(%Y-%m-%d %H:%M:%S) agent Agent( modelOllama(idqwen2.5:7b), knowledge_baseknowledge_base, search_knowledgeTrue, tools[get_current_time], show_tool_callsTrue, )show_tool_callsTrue会把模型决定调用哪个函数的过程显示出来。这非常有用因为它暴露了模型的内在推理链路。如果你发现模型什么问题都先去调函数、而不是先查知识库说明 Prompt 里的工具使用说明需要调整或者工具描述写得太宽泛了。工具调用的本质是把“检索文档”和“执行计算”这两件不同的事分开文档检索走知识库实时信息走函数。这样职责清晰后期也容易加权限控制比如某些函数只允许特定角色调用。4.3 多 Agent 分工把问题拆解得更细单 Agent 能处理不少任务但碰到复杂业务一个 Agent 包打天下会越来越笨拙。Phidata 支持把多个 Agent 组合成 Team不同 Agent 负责不同专业领域。举个例子假设知识库里有产品手册也有售后政策。你可以建两个 Agent产品Agent专注回答产品参数、使用方法。售后Agent专注保修、退换货政策。再建一个“调度 Agent”负责理解用户问题、决定转发给哪个子 Agent、最后汇总结果。这种架构的好处是每个 Agent 的知识库更聚焦Prompt 也更短回答质量更稳定。代价是系统复杂度上升不建议第一版就上先让单个 Agent 把主流程跑通再说。5. 生产环境调优检索质量与稳定性5.1 分块参数chunk_size 与 overlap 怎么调RAG 回答质量很大程度上取决于文本分块。分块太粗一段里混了多个主题检索时召回的内容不聚焦分块太细语义被切碎模型拿到的上下文支离破碎。Phidata 默认加载文档后会把文本切分成小块常见的默认值大约在 300 字符左右、重叠 60 字符左右。我实际用下来的经验如下文档类型建议 chunk_size建议 overlap理由产品手册/制度文件300-50050-80条款相对独立保留些上下文即可论文/长叙述文档500-80080-120语义跨度大需要更长上下文对话/FAQ200-30020-40QA 结构紧凑分块太大会混入无关Q你可以用一个小脚本打印切块后的片段直观感受分块效果。如果看到一块里混杂了两个完全无关的主题就该调小 chunk_size如果发现一个完整的答案被拦腰截断就该调大 chunk_size 或增加 overlap。5.2 向量索引HNSW 与参数调优PgVector 支持两种索引IVFFlat 和 HNSW。IVFFlat 需要先有足够数据才能建索引而且要指定聚类中心数量不够灵活。HNSW 则是一种近似最近邻的图索引查询速度快构建参数相对少更适合大多数应用场景。建索引的 SQL 大概是这样的CREATE INDEX ON pdf_documents USING hnsw (embedding vector_cosine_ops);分片是 Phidata 自动建的但索引策略可以自己控制。如果你发现检索变慢或者召回质量下降可以先检查索引是否生效EXPLAIN ANALYZE SELECT * FROM pdf_documents ORDER BY embedding [向量] LIMIT 10;注意vector_cosine_ops是针对余弦距离的操作符类如果你用的是欧氏距离要换成vector_l2_ops。Phidata 默认的检索方式通常与余弦距离保持一致所以一般用vector_cosine_ops就行。5.3 数据库连接与并发处理上线之后多个用户同时提问每个问题都会触发知识库检索PostgreSQL 连接数可能瞬间被打爆。SQLAlchemy 的连接池默认值不一定够用建议根据并发量调整。Phidata 的 PgVector 底层使用 SQLAlchemy所以在连接串里加查询参数可以控制连接池大小DB_URL postgresqlpsycopg://ai:ailocalhost:5532/ai?pool_size10max_overflow20pool_size10表示保持 10 个连接max_overflow20表示高峰时可以临时扩充到 30。如果你的机器资源有限这个数字不要调太大否则连接风暴会反过来拖垮数据库。还有一点容易被忽略定期重载知识库。文档更新后旧向量还留在表里不重载的话检索到的可能是过期内容。你可以写一个定时任务在凌晨低峰期调用knowledge_base.load()用增量更新方式同步变化。配合日志记录哪天回答出错了也能清楚到底是哪份文档里的旧内容导致的问题。6. 常见问题与排查技巧实录6.1 加载文档之后检索结果总为空这是新手最容易遇到的问题。可能的原因有三个表和索引没建成功检查pdf_documents表是否真的存在SELECT COUNT(*) FROM pdf_documents;看有没有数据。向量化失败如果 embedding 模型没配好加载时不会报错但库里全是空向量。查看加载日志出现 embedding 相关警告就说明有问题。检索条件过于严格用户的提问方式和文档原文差异太大。先搜一个文档里的原文片段如果原文都搜不到那一定是链路问题如果原文能搜到说明又是语义匹配的调优问题。6.2 更换 embedding 模型后维度不一致之前说过不同 embedding 模型输出的向量维度不同。如果你之前用的是 768 维后来换成了 1024 维的模型直接跑会报维度错误。这时需要把对应表删掉重建或者先TRUNCATE再重新load(recreateTrue)。更稳妥的做法是从第一天起就把 embedding 模型固定下来不要在生产环境频繁切换。升级模型前先在测试环境完整验证一轮确认检索质量确实提升了再动手。6.3 回答不引用文档感觉像在瞎编我在第 3 节提到add_referencesTrue这一步只是把来源附在回答里但 Prompt 里的 Instructions 才是决定模型“要不要引用文档”的关键。我在项目里经常给 Agent 加这样一条当你引用文档内容时必须标明来源文件的名称和对应章节。 如果用户问你一个你无法从文档中确认的问题请回答“该问题在现有文档中未找到明确说明”。这样能大幅减少幻觉。你还可以在 Agent 里打开详细日志把检索到的片段打印出来确认模型到底看了哪些内容。很多时候回答不准不是模型不行而是检索回来的内容里确实没有正确答案。6.4 PostgreSQL 权限不足无法创建扩展Docker 方式启动的 PostgreSQL 一般没问题但你用已有实例时可能遇到当前用户没有超级权限导致CREATE EXTENSION vector失败。解决方法是切换到超级用户或者让管理员先创建好扩展再给业务用户授权。不要在一个共享数据库里用超级用户跑日常业务那是运维事故的温床。6.5 我踩过几次坑之后想分享几个心得第一知识库的内容质量比模型大小重要得多。我见过有人换了更大的模型回答反而变差了原因就是文档本身过时、矛盾、格式混乱。先把文档整理干净比换模型更划算。第二先小步验证再扩大规模。不要第一天就把一百份文档全塞进去先拿一份文档打通链路确认每一个环节都正常再逐步加文档。全量加载之后如果回答质量下降你也知道是新加的哪批文档出了问题。第三把检索日志当成产品监控来做。每次问答都记录一下“检索了哪些片段、命中了哪份文档、得分是多少”。有了这些日志用户反馈“回答不对”时你能快速定位是检索没召回还是模型没理解。这一步在早期省了我大量时间。第四注意知识库的权限边界。企业内部文档常常混杂着公开信息和敏感内容向量检索本身不会区分权限。如果系统要给不同角色开放不同范围的知识库一定要在应用层做好文档级别的访问控制不要让向量表裸奔在公网环境。最后的一点个人体会这套 Phidata PgVector 的组合我最喜欢的地方是它没有逼着你把技术栈拆得七零八落。一个 Python 环境、一个 PostgreSQL 实例就能把一个智能问答助手从原型带到生产。比起那些动辄要部署三四个服务的方案这套简化掉的运维复杂度会变成你后续迭代的信心来源。我在实际使用中最大的感受是RAG 的技术门槛没那么高真正难的是把检索质量调稳、把知识库内容管好以及让 Agent 在“知道”和“不知道”之间诚实切换。如果你正要开始做智能 RAG 助手不妨先按这篇文章跑通最小闭环再根据你自己的文档特点去调整分块和检索参数。接下来你还可以往多模态文档、结构化知识图谱、自动知识库更新这些方向去扩展每一步都有 Phidata 的组件在背后撑着不会让你推倒重来。