1. ragflow v0.26.3 到底改了什么值不值得升如果你正在用 ragflow 搭知识库或者刚评估完准备上生产v0.26.3 这个版本值得单独拿出来看一遍。它不是一个只修几个 bug 的小版本而是把数据接入、文档解析、Agent 工具链、Go API 几条线同时往前推了一截。核心检索词先摆出来ragflow v0.26.3 新增了 Google BigQuery 数据源连接器文件摄取集成了布局感知的 SoMark OCR 解析器MCP Server 多了两个工具批量上传支持部分成功Go API 继续补强另外还有一大批前后端修复。适合谁看已经在跑 ragflow 的运维和开发想知道升级后哪些行为会变正在评估 ragflow 的团队想判断它在企业数据接入和复杂文档解析上够不够用以及做 Agent 工作流、需要通过 MCP 跟 ragflow 交互的开发者。我试过把这一版的变更按“会不会影响我现有部署”来分类结论是BigQuery 和 SoMark OCR 属于新增能力不升也能用但升了能解锁新场景批量上传部分成功、Ollama 模型访问修复、聊天引用误删修复属于行为修正建议尽快升Go API 和 MCP 的扩展则是给二次开发留的口子。下面按可跟做的顺序拆开讲每一步都给配置片段和验证动作。2. 升级前先把 TaoToken 这条链路准备好ragflow 本身是自托管的知识库系统但你在实际用的时候模型调用这一层往往需要单独接。不管是本地 Ollama 还是云端模型如果想让 ragflow 的对话、Agent、OCR 后处理这些环节稳定跑起来建议先把模型访问的入口统一好。TaoToken 在这里的角色是提供一个兼容 OpenAI 风格的 API 入口你可以在 ragflow 的模型提供商配置里直接填它的地址和 Key省去每个模型单独适配的麻烦。具体来说ragflow 的模型设置里支持自定义 OpenAI 兼容端点。你需要准备两样东西一个 API Key一个 Base URL。Key 在控制台生成地址用https://taotoken.net/api。如果你还没建过 Key可以先去控制台的 API Keys 页面创建一个然后回到 ragflow 的模型提供商配置里填进去。这一步不是必须的但如果你打算用 ragflow 的 Agent 能力或者跑批量文档解析后的摘要、问答生成提前把模型入口配好会省很多事。尤其是 v0.26.3 修复了 Ollama 提供商接入后报Failed to access model(name) using this api key的问题说明模型接入这块官方也在持续打磨你用兼容端点的方式接入会更稳。3. 可复制配置BigQuery 接入与 SoMark OCR 开启3.1 BigQuery 数据源连接器怎么配v0.26.3 新增了 Google BigQuery 作为数据源连接器主要用于文档摄取和增量同步。配置入口在 ragflow 的数据源管理里你需要准备 BigQuery 的服务账号 JSON 密钥以及项目 ID、数据集 ID。配置片段大致长这样字段名以你实际界面为准{ type: bigquery, project_id: your-gcp-project, dataset_id: your_dataset, credentials_json: /path/to/service-account.json, sync_mode: incremental, sync_interval_minutes: 30 }几个关键点sync_mode选incremental才会走增量同步否则每次全量拉credentials_json指向服务账号文件确保 ragflow 进程有读权限sync_interval_minutes控制轮询频率生产环境别设太短避免打爆 BigQuery 的配额。配完之后在数据源列表里点同步观察日志里有没有bigquery sync started和rows fetched这类输出。如果卡在认证阶段大概率是服务账号缺少 BigQuery Data Viewer 和 Job User 权限。3.2 SoMark OCR 解析器怎么启用SoMark OCR 是这一版文件摄取里新集成的布局感知解析器专门处理表格、图像、复杂版面。它不是一个独立开关而是作为解析器选项出现在文档解析配置里。你在创建知识库或者上传文档时解析方法那一栏应该能看到 SoMark 相关的选项。如果你是通过 API 走摄取流水线可以在请求体里指定解析器{ parser_id: somark, parser_config: { layout_aware: true, extract_tables: true, extract_images: true } }实测下来SoMark 对表格密集的 PDF 提升比较明显尤其是那种跨页表格和图文混排的文档。但要注意布局感知解析比普通文本抽取慢批量导入时建议先小批量试确认解析质量和耗时再放大。3.3 批量上传部分成功的验证这一版后端给批量文档上传加了部分成功机制。以前一个文件失败整批回滚现在单个失败不影响其他文件。你可以在上传接口的返回里看到每个文件的状态{ total: 20, success: 18, failed: 2, failed_files: [ {name: bad.pdf, reason: parse error}, {name: locked.docx, reason: permission denied} ] }验证方法故意混一个格式损坏的文件进批次看返回里 success 是不是等于总数减失败数失败文件有没有单独列出来。这个改动对运维很友好不用再因为一个坏文件重跑整批。4. 验证请求MCP 工具与 Go API 怎么测4.1 MCP 新增的两个工具v0.26.3 给 RAGFlow MCP Server 加了两个工具ragflow_list_datasets和ragflow_list_chats。前者枚举数据集后者枚举聊天记录。如果你在用外部 Agent 编排工具通过 MCP 调 ragflow这两个工具能让你先列出可用资源再决定操作哪个。调用方式取决于你的 MCP 客户端但工具名和参数结构是固定的。ragflow_list_datasets一般不需要额外参数返回数据集 ID 和名称列表ragflow_list_chats可能需要指定用户或会话范围。测的时候先确认 MCP Server 已经启动然后在客户端里调用这两个工具看返回的 JSON 结构是否符合预期。另外这一版还修了一个关键问题canvas 执行后关闭 MCP 会话避免连接泄漏。如果你之前跑长时间工作流发现连接数一直涨升级后应该能缓解。4.2 Go API 的验证动作Go API 这一版补了很多包括聊天 completions 的 Go 版本、sessions message update、chatbots info、searchbots detail、chat recommendation 等。验证方式很简单用 curl 打几个新端点curl -X POST https://your-ragflow-host/api/v1/chat/completions \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d {dialog_id:your_dialog_id,messages:[{role:user,content:test}]}如果返回正常的 completion 结构说明 Go 侧聊天链路通了。再试一下 mindmap 端点curl https://your-ragflow-host/api/v1/chat/mindmap \ -H Authorization: Bearer YOUR_API_KEY注意这一版有个回滚聊天会话消息删除与反馈接口先新增后回滚了实现所以如果你在文档里看到这个接口实际调用可能返回未实现。以你部署版本的接口文档为准。5. 本篇常见错排查升级到 v0.26.3 后最容易踩的几个坑我列一下。第一个是 Ollama 模型访问报错。虽然这一版修了Failed to access model(name) using this api key但如果你升级后还报先检查 Ollama 服务本身是否可达以及 ragflow 配置里的模型名是否和 Ollama 里ollama list显示的一致。修复的是 ragflow 侧的鉴权逻辑不是 Ollama 本身的问题。第二个是聊天引用误删。这一版修了删除一组用户与助手消息时误删上一轮引用的问题。如果你升级前遇到过删消息后上下文错乱升级后建议清一下浏览器缓存再测避免旧前端逻辑干扰。第三个是文档解析相关。这一版处理了/datasets/{dataset_id}/chunks无法解析摄取流水线的问题改用/documents/ingest。如果你之前用 chunks 端点做自定义导入一直失败现在应该切到 ingest 端点。另外 DOCX 解析器有新增和修复未编号标题样式处理也改了如果你有大量 Word 文档升级后重新解析一遍看效果。第四个是构建和依赖。这一版用.a替换.so来适配 pdfium、pdf_oxide、office_oxide还修了 g 11 不兼容。如果你是从源码构建升级后记得重新跑依赖下载脚本别直接复用旧的构建产物。第五个是认证和权限。多个图片、预览、缩略图接口的 BETA 鉴权修了Searchbot BETA 鉴权也修了。如果你之前遇到图片加载不出来或者 403升级后应该正常。另外 Python 侧修了单点登录和修改密码后强制重新登录企业环境用 SSO 的注意测一下。6. 升级决策与后续接入建议判断要不要升 v0.26.3看你的痛点在哪。如果你需要从 BigQuery 这类云数仓持续同步数据或者知识库里表格、图文混排文档多这一版的新能力直接对口。如果你被批量上传整批失败、Ollama 模型访问报错、聊天引用错乱这些问题困扰过这一版就是修这些的。如果你在做 Agent 和 MCP 方向的二次开发新增的工具和 Go API 补强能省不少适配工作。升级动作上建议先在测试环境跑一遍完整流程BigQuery 同步、SoMark 解析、批量上传、MCP 工具调用、Go API 请求。确认没问题再上生产。生产环境升级前备份数据库和上传的文件目录尤其是知识库索引数据。后续接入方面模型调用这一层如果你还没统一入口可以先把 API Key 建好Base URL 用https://taotoken.net/api在 ragflow 的模型提供商里配成 OpenAI 兼容端点。这样不管是聊天、Agent 还是文档后处理都走同一个入口排查问题也方便。需要长期跑编码类 Agent 任务的可以看看 Coding Plan 这类方案把模型调用和任务编排分开管理。接入过程中遇到鉴权或端点问题直接翻接入文档比在群里问快。