开源AI搜索聚合平台MiYo.AI：架构拆解与本地部署实践

这两年只要聊到AI搜索，大家开口就是“哪家答案更聪明”“哪家引用更全”。我自己收藏夹里至少躺了五六个AI搜索工具，可每次真要用的时候反而犯难：同一个问题要在好几个平台之间来回切，光是复制粘贴问题、对比答案就得折腾好几分钟。后来在GitHub上看到米柚AI搜索（MiYo.AI）这个项目，第一反应是“又是套壳聚合”，但把它拉下来跑了一遍之后，我的想法变了。它是一个实时智能搜索聚合平台，核心思路是把多路搜索引擎的结果抓回来，交给大模型做过滤、合并、总结，最后以带引用的完整回答呈现出来。最打动我的一点是它开源，这意味着我可以自己部署、自己决定接什么搜索源、换成什么模型，数据全在自己手里。

如果你也在纠结AI搜索工具太多、答案太分散，或者想给自己的团队搭一个内部搜索问答服务，这篇文章应该能给你一个相对完整的参考。我会从项目定位、架构拆解、本地部署、源码导读到踩坑实录，把我实际操作的过程和思考都写出来。

1. 项目定位：为什么“实时聚合”比“单点智能”更实用

1.1 单一AI搜索产品的两个老问题

市面上的AI搜索产品其实都在解决同一个问题：让用户用自然语言提问，然后返回一个“看起来像人写的”答案。但用多了就会发现，单点产品有两个很难绕过去的坎。

第一是信息覆盖范围有限。每个产品背后的搜索源都不一样，有的偏技术内容，有的偏新闻资讯，有的偏社区讨论。你以为自己问的是“Java 1.8可用的开源审批工作流有哪些”，结果某个平台返回的全是博客站的内容，真正靠谱的GitHub项目却被漏掉了。第二是实时性不足。很多模型的知识截止日期是固定的，你问“今天某个开源项目的最新版本发没发”，它只能老老实实告诉你“我的知识截止到某年某月”。这不怪模型，但如果搜索聚合层能实时抓取网页，再让模型基于这些新鲜素材来回答，问题就解决了。

MiYo.AI的定位恰好卡在这两个痛点上：它自己不生产搜索结果，而是做聚合、清洗和再组织。你可以把它理解成一个“信息买手”——从多个货源市场进货，挑出品相好的，再请一个大厨做成一道菜端给你。买手本身不会种菜，但经它一整合，菜比单家市场丰富得多。

1.2 开源带来的三个实际好处

选择开源版本，意味着三件事你可以自己说了算：搜索源可以自定义，模型端点可以替换，数据不需要经过第三方服务器。

举个很具体的例子，我在公司内部用的时候，不希望每一条内部检索记录都跑到公网AI服务上。MiYo.AI部署在内网之后，搜索请求走的是自己的服务器，大模型可以接本地部署的推理服务，整个过程都在内网闭环里完成。对于有数据合规要求的团队来说，这种私有化能力几乎是刚需。对于个人玩家，开源还意味着你能看清它的请求链路，出问题的时候不是对着黑盒猜，而是可以打开日志、翻源码一步步排查。

1.3 哪些人适合用它

我的判断是三类人最值得试试：一是有自建知识库或内部搜索需求的开发者，二是在多个AI搜索工具之间反复横跳的重度用户，三是想学习搜索聚合、RAG、流式输出这类工程实现的同学。如果你只是偶尔用AI搜索查个菜谱，那直接用在线服务就够了，没必要折腾部署。但如果你想让它成为一个可以按自己想法改造的基础设施，MiYo.AI有足够的发挥空间。

2. 整体架构拆解：一个请求进来之后发生了什么

2.1 四层架构的分工逻辑

通读源码之后，我把它在逻辑上分成了四层：应用层、接入层、智能层、存储层。这个分层不是刻意做出来的，而是随着功能扩展自然长成的。

应用层就是用户能看到的界面和API入口，负责接收问题、展示流式回答；接入层是搜索源的适配器集合，每个搜索源对应一个适配器；智能层负责查询改写、结果去重、相关性打分、最终答案生成；存储层管缓存、会话历史、向量索引。四层各管一摊，替换任何一层都不需要动其他层。比如你不想用默认的前端界面，只保留API服务，那直接把应用层拆掉就行；想换一套大模型，也只需要改智能层的模型端点配置。

这种分层设计最大的好处是“可插拔”。刚开始搭建的时候我总觉得模块多很麻烦，但后来往里加搜索源、换模型的时候才发现，清晰的边界比什么都重要。它不会出现改一个搜索源导致总结模块报错的情况，因为两者之间只有标准数据接口，没有隐式的依赖。

2.2 为什么用“并行抓取+统一重排”而不是“逐个串行”

我最初想简单点：一个搜索源返回结果，直接交给模型总结，完事。但实际用下来，单一搜索源的结果质量波动很大，今天这个源给的网页好，明天就变成一堆SEO垃圾。MiYo.AI的做法是同时向多个源发起请求，然后把所有结果汇在一起做重排。

并行抓取的意义很好理解——多个请求同时发，总耗时取决于最慢的那个源，而不是所有源耗时相加。它的实现基础是异步IO，底层用httpx的AsyncClient配合asyncio的gather来并发请求。还有一个容易被忽略的点：统一重排。多个源返回的结果会有大量重复，比如同一个GitHub仓库被四个源都收录了，如果不做归一化去重，模型总结的时候会被重复信息干扰，浪费宝贵的上下文窗口。重排环节会根据URL、标题相似度做去重，再结合时间新鲜度和关键字匹配度打分排序。

值得一提的是，这里的时间新鲜度不是简单看发布时间，而是一个加权因子。实现里默认对新近内容给更高的分数，如果设置了“实时敏感模式”，还会把查询改写后的关键词和结果里的时间戳做匹配，避免把去年的新闻当成今天的头条推给模型。

2.3 一次查询的完整路径

我从日志里梳理了一条最典型的请求路径，方便你理解整件事的先后顺序。用户在输入框里提问，前端把问题发送到后端API；后端先检查Redis里有没有相同问题的缓存，如果有就直接返回；没有的话，进入查询改写阶段，大模型把口语化问题改写成若干适合搜索引擎的关键词组。

接着接入层根据关键词组，分别到配置好的搜索源抓取结果，每个源设置独立的超时时间，谁慢谁就被跳过。抓回来的原始结果进入智能层，先做HTML转纯文本、URL归一化、标题去重，再按相关性和时效性重排，截取前N条。然后系统组装一份包含搜索结果摘要的prompt，交给大模型生成最终回答，同时保留引用来源。最后前端以SSE流式方式把答案一个字一个字显示出来，用户觉得答案可接受，结果就被写进缓存，下次提问直接命中。

整个流程看起来很顺，但每个环节都有不少细节坑，后面我会逐个展开。

3. 从零部署MiYo.AI：我把踩过的板子全记下来了

3.1 环境准备与依赖选型

先说结论：在满足条件的情况下，优先用Docker Compose部署，因为它已经把依赖打包好了。我用的是Ubuntu 22.04服务器，两核四G内存，部署起来没有任何压力。如果你只是本地体验，Windows上用WSL2加Docker Desktop也没问题。

依赖上主要需要三样：Docker和Docker Compose插件、一个可以访问的大模型推理服务、以及若干搜索源的访问凭证。这里要特别提醒，MiYo.AI默认的设计是接入公开搜索源，所以“实时性”很大程度上取决于这些搜索源是否给你开放接口。有的搜索源限制每分钟请求次数，有的需要API Key，部署前先把凭证准备好，不然后面配置阶段会很折腾。

如果你不想用自己的付费搜索API，也可以用项目内置的“网页解析型”源。这类源不需要官方API，而是通过抓取搜索结果页面来工作。但它对页面结构变化非常敏感，一旦对方改版，你可能需要更新适配器代码，这就是开源项目的一个典型维护成本。

3.2 用Docker Compose一键拉起服务

仓库根目录下有一个docker-compose.yml，我本地跑起来的命令非常简单：

bash复制git clone <项目仓库地址> miyo-ai
cd miyo-ai
cp .env.example .env
docker compose up -d

首次启动会拉取几个镜像：后端服务镜像、Redis镜像，如果有向量库需求还会拉一个pgvector镜像。整个拉取时间取决于网络情况，国内服务器建议提前配置好镜像加速。启动成功后，通过 docker compose ps 能看到后端服务和Redis都处于healthy状态。

这里有个细节，默认compose文件里前后端可能做在一个镜像里，也可以拆成两个服务。我的建议是拆开跑，前端静态文件用Nginx单独提供服务，后端API走独立端口。虽然拆开之后配置会多两步，但后续你改前端样式的时候不用重启后端，调试效率高很多。

环境变量配置是部署最容易出错的环节。.env文件里最重要的几项是模型服务的地址、模型名称、搜索源的凭证、以及缓存超时时间。我在第一次配置的时候把模型服务地址写成了http://localhost:8000，容器里面访问不到，排查了半天才发现应该是宿主机IP或者Docker网络内的服务名。这个坑真的很常见。

3.3 配置搜索源和模型端点

MiYo.AI的搜索源配置集中在config/sources.yaml里，格式非常直观，我这里给一个简化版的示例：

yaml复制sources:
  - name: web_search_a
    type: json_api
    endpoint: "https://api.example.com/search"
    api_key: "${SEARCH_API_KEY_A}"
    timeout: 8
    weight: 1.0
  - name: web_search_b
    type: html_parser
    endpoint: "https://example.com/search?q={query}"
    parse_rules:
      result_item: "div.result-item"
      title: "h2.title"
      url: "a.result-link@href"
      snippet: "p.snippet"
    timeout: 10
    weight: 0.8

每个搜索源可以设置独立的超时时间，这个设计很贴心。有的源响应快但内容质量一般，有的源响应慢但权威性高，通过权重可以控制它们在最终重排中的话语权。我当时把两个深度技术搜索源权重调得高一些，普通网页搜索权重调低，实测下来整体答案质量有明显提升。

模型端点的配置则指向任意OpenAI兼容接口，本地部署的模型服务也好，云端模型也好，只要接口格式兼容都能接。我先后试过云端模型和本地量化模型，最终选择了一种混合策略：查询改写用便宜快速的小模型，答案生成用参数更大的主力模型。这样既省钱，又保证答案质量。MiYo.AI支持给不同环节指定不同模型，这个能力在同类项目里不多见。

3.4 用真实问题验证部署结果

配置完成后，我习惯用一个带时效性的问题来验证系统是否真的“实时”：“Python 3.13最新稳定版本是哪一版”。如果系统返回的是模型知识截止日期之前的老版本信息，说明搜索聚合环节没生效；如果它能给出包含当前版本号、发布说明链接的答案，并且每个关键句后面都有引用角标，说明整条链路是通的。

我第一次跑通的时候，答案末尾带着五个引用来源，点开都能验证，那种感觉真的很爽。验证完别忘了做一个逆向测试：临时停掉所有搜索源，再问同一个问题，观察系统是否能够明确告诉你“没有获取到实时搜索结果”，以及它是否拒绝编造。这个测试能看出系统面对信息缺失时的诚实度，MiYo.AI在这块处理得不错，它不会在没有任何搜索素材的情况下硬生成答案，而是会降低置信度。

4. 核心源码导读：请求生命周期与关键参数解析

4.1 输入清洗与意图判断

进入智能层的第一步不是急着改写查询，而是清洗输入。代码里有一个clean_query函数，用来去除多余空格、合并连续标点、过滤掉空字符串。看起来很简单，但实际很关键。我在测试中发现，如果用户输入末尾带了多余空格，某些搜索源的URL拼接会把空格编码成%20，导致搜索结果明显偏离意图。

意图判断是另一个容易被忽视的模块。MiYo.AI会判断问题是“实时性问题”还是“通用知识问题”。如果是实时性问题，就提高搜索结果的时效性权重；如果是通用知识问题，就按常规逻辑处理。判断方法不是正则匹配这么简单，而是结合关键词时态和问题中的具体名词来做轻量级启发式判断。比如问题里出现“最新版本”“今天”“本周”字样，系统会倾向于实时敏感模式。

这里有个权衡：意图判断如果太激进，用户随便问个概念性问题也会被当成实时问题，结果总结出来的答案干巴巴的，全是网页摘要流水账；如果太保守，真正需要实时的新闻类问题又抓不到最新信息。默认策略是折中，只在信号非常明确时才切到实时敏感模式，平时保持标准模式。我实测下来这个默认选择是合理的，不建议一上来就把灵敏度拉满。

4.2 多搜索源并行执行的控制逻辑

并行执行这部分代码是我读得最仔细的地方。核心逻辑并不复杂，本质上就是一句话：创建异步任务列表，用asyncio.gather等它们全部完成。

python复制async def fetch_all_sources(sources, query):
    semaphore = asyncio.Semaphore(8)
    tasks = [fetch_with_semaphore(semaphore, s, query) for s in sources]
    results = await asyncio.gather(*tasks, return_exceptions=True)
    return [r for r in results if r is not None]

信号量Semaphore的作用是限制最大并发数，我最初以为并发越大越好，后来发现有的搜索源对短时间内的请求数量非常敏感，8路并发已经是很多免费接口的容忍上限。如果并发数调到16，大概率会触发限流，导致一批429响应。对你我来说，这个参数是个需要小心调优的点。

注意代码里用到了return_exceptions=True。这意味着某个搜索源超时或者抛异常，不会拖垮整批请求，而是会把异常当作结果返回，最后由过滤逻辑把异常项剔除。如果没有这个参数，一个源出错就会让整个请求失败，这是多源聚合项目里最容易踩的坑之一。

每个搜索源内部还有一层超时控制。HTTP请求会设置连接超时和读取超时，分别控制建立连接和读取响应的最长等待时间。我自己的习惯是连接超时3秒，读取超时8秒，超过就放弃。这样即使某个源服务端响应极慢，用户的等待时间仍然可控。

4.3 结果重排与prompt组装

重排不是简单的分数相加，而是把多个维度归一化后求加权和。我从代码里梳理出来的关键因子包括：关键词命中率、来源权重、页面时效性、以及文本质量信号。文本质量信号很有意思，它会根据页面里是否有广告痕迹、标题是否过度夸张、正文长度是否合理来做基础判断。这个机制原始朴素，但能过滤掉不少内容农场页面。

python复制def rerank_results(results):
    scored = []
    for item in results:
        score = (0.4 * item.keyword_hit_score) + (0.3 * item.source_weight) + (0.2 * item.freshness_score) + (0.1 * item.quality_signal)
        scored.append((score, item))
    scored.sort(key=lambda x: x[0], reverse=True)
    top_n = [item for score, item in scored[:5]]
    return top_n

取前5条是默认值。这个数字不是拍脑袋定的。太少结果会缺失信息广度，太多结果会撑爆模型的上下文窗口，导致生成开销变大、响应变慢。5条平衡下来比较合适，目标12条相对传统搜索算“窄”，但对总结式回答来说，5条高质量网页已经足够。

prompt组装是我觉得这个项目做得很成熟的地方。它不会把整页文本塞给模型，而是让每个搜索源返回的snippet先经过压缩，然后以“序号+标题+摘要+URL”的结构拼进prompt。模型收到的是类似“根据以下搜索结果回答问题，若信息不足请直接说明”的指令。这样做既节省token，又方便模型输出引用角标。如果你改了重排条数，记得也调整prompt里的引用数量上限，不然模型可能引用不存在的第6条来源。

4.4 流式输出的实现细节

流式输出用的是SSE（Server-Sent Events），后端将模型返回的token流逐步推送给浏览器。很多人说流式输出不就是在FastAPI里加一个StreamingResponse吗，实际做起来没那么简单。MiYo.AI这里做了两层处理：一层是透传模型服务的流式输出，另一层是在流中注入引用标记的渲染指令。

前端收到流式数据后，如果某个片段包含引用索引，会高亮显示成可点击的角标。为了保证流式输出过程中客户端能区分“答案文本”和“引用标记”，代码里定义了一个简单的协议前缀：普通文本直接发送，引用标记以特殊字段名单独推送。我第一次看这里的时候觉得方案有点“笨”，但试过之后发现，协议简单反而是最大的优点，出了问题一眼就能从日志里看到是哪一段的格式错了。

流式输出还有一个需要考虑的点是错误处理。模型生成到一半可能断开连接，如果前端不做处理，用户会看到半个答案。MiYo.AI的做法是：底层流异常时，后端会推送一条错误消息，前端接收后立即停止渲染并显示“回答中断”的提示。这个细节虽然不常被提到，但对使用体验的影响非常大。

5. 我在实际使用中踩过的坑与排查技巧

5.1 搜索结果返回乱码

现象：从某个搜索源抓回来的标题和摘要变成一堆乱码。排查了一圈发现是编码问题。很多网页用的是GBK编码，但请求时默认按UTF-8解析，自然全是乱码。解决办法是在适配器里根据响应头判断charset，必要时用chardet做编码探测。这个坑在北方的政府类网站和技术论坛上尤其常见，如果你接的是一个内容比较传统的搜索源，一定要在适配器里加上编码兼容逻辑。

5.2 模型上下文溢出导致回答被截断

现象：搜索结果内容一多，模型输出到一半就停了，日志里报“maximum context length exceeded”。表面上是搜索源返回的网页太长，实际上是我把重排后的Top N设成了10条，每条snippet最长设成了800字，加起来的上下文远超模型的承受范围。解决办法很简单：压缩snippet到300字左右，Top N降回5条，并开启结果摘要预压缩。如果你的模型上下文窗口只有8K，建议Top N控制在4条以内。

5.3 Docker容器时间不同步

现象：查看日志时发现每一条记录的时间都比服务器慢了8个小时，刚开始还以为是日志框架的问题，后来发现是容器内默认时区是UTC。AI搜索这种对实时性敏感的应用，时间错乱会直接影响时效性计算。解决办法是在docker-compose.yml里给服务加两行环境变量：TZ=Asia/Shanghai，同时挂载宿主机的/etc/localtime到容器内。加了之后重启容器，时间戳就正常了。

5.4 搜索源限流与封禁

现象：运行一段时间后，某个搜索源开始持续返回错误码，严重时连正常的少量请求也被拒。这类问题基本无解，只能从缓存和降级策略上下手。我当时的做法是把Redis缓存TTL从5分钟调到15分钟，同一个问题短时间内不会反复触发搜索源。同时给每个源配置了降级标记：如果连续失败5次，自动熔断10分钟，不再向这个源发请求，直接让其他源顶上。

5.5 常见问题速查表

排查过程中我最大的体会是：优先看日志，别猜。MiYo.AI后端日志会打印每个搜索源的请求状态和耗时，一眼就能看出是哪条链路出了问题。很多时候你觉得是模型不好用，结果是因为某个搜索源默默挂了，模型等不到素材才“胡言乱语”。

6. 拿来改造成自己的工具：三个值得一试的方向

6.1 个人知识库问答

我后来做的一个改造是给MiYo.AI接入了本地的知识库索引。具体做法是：把个人笔记、书签、收藏的文章同步进向量数据库，然后在搜索源列表里加了一个“知识库源”。这样提问时，系统同时搜索公网和私有知识库，模型总结的时候会把内外部信息融合在一起回答。

这种改造的收益很直观。以前我查一个项目的背景资料，要在浏览器、笔记软件、AI搜索之间来回切换，现在一个入口全搞定。而且私有知识库里的信息不会经过公网模型，对内容敏感的场景更安心。由于MiYo.AI的搜索源是标准接口，这个改造的代码量并不大，核心只是写一个向量检索函数并返回统一结构的结果。

6.2 团队内部信息雷达

如果你在团队里维护一个技术选型或竞品分析的需求，MiYo.AI这套聚合搜索能力可以改造成一个定时信息雷达。原理很简单：写一个定时任务，每隔一段时间自动把固定问题列表丢给搜索聚合服务，把返回的答案存起来，发现新结果时通过Webhook推送提醒到企业群。

这个方向最有价值的地方不是“每日总结”，而是“变化检测”。因为聚合了多个源，来源A出现的信息可能来源B几天后才覆盖，通过定时对比重排结果的指纹，可以在第一时间发现某条关键信息出现在哪些平台。我当时用这个思路盯了某一个开源项目的版本发布动态，实测能比传统搜索快半天左右。

6.3 对外提供聚合搜索API

如果你有后端开发经验，还可以把MiYo.AI包装成一个处理学生作业、编程问题的AI问答API服务，用于个人网站的智能助理。因为项目本身已经提供了完整的API接口，你只需要在前端页面里嵌入一个对话窗口，后端接收问题后调用MiYo.AI的服务，再把结果返回即可。

这里有一个配置参数必须注意：API Rate Limit。对外提供服务后，很容易遇到恶意刷请求的问题。MiYo.AI虽然自带了基础限流，但建议在网关层再加一层IP级限流和Token配额管理。我个人在实际部署中就把默认的单用户每分钟30次限制降到了10次，成本压力明显减小，正常用户的使用体验也没有受到影响。

最后再分享一个实际操作的小技巧

如果你决定自部署MiYo.AI，我强烈建议把搜索结果的原始返回数据也缓存一份，定期清理，而不是只看最终的AI回答。原因很朴素：AI回答是加工过的“熟食”，原始搜索结果才是“生鲜食材”。当某一天模型换了版本，或者你想换一个prompt风格重新生成答案时，如果还保存着原始搜索数据，你就不需要再次请求搜索源，既省钱又省时间。我在项目里就是加了一个简单的本地JSON存储目录，按天归档，跑了三个月，磁盘占用不到2G，但每次优化prompt之后的对比实验都变得无比方便。

另外还有一个容易被忽略的运维习惯：每次升级版本之前，先导出当前环境变量和配置文件。我有一次升级后忘记迁移自定义搜索源配置，导致服务启动后所有源都失效，花了将近半小时才想起是配置文件被覆盖了。后来我习惯把.config目录纳入版本管理，重要变更都走提交记录，这样就算出了问题也能快速回滚到正常状态。

MiYo.AI不是一个“装完就完”的项目，它的乐趣和深度都在后面。你可以不断调整重排权重，换不同的模型组合，甚至给它加新的搜索源适配器。这种折腾的过程，才是开源项目最有价值的部分。希望这篇博客能帮你快速把它跑起来，少踩一些我踩过的坑。