agno 知识库如何配置混合搜索并用 Cohere reranker 做两阶段重排提升检索质量？

2026-09-09 11:44:54作者：何将鹤

如果你用 agno 的 Knowledge 组件给 Agent 接入文档检索，会遇到两类典型问题：纯向量搜索在关键词精确匹配场景下容易漏掉相关分片，纯关键词搜索又抓不住语义相近但用词不同的内容；另外首轮召回的候选集里常混入不相关的分片，直接影响最终回答质量。agno 的 knowledge cookbook 给出的操作路径是：先用 SearchType.hybrid（向量 + 关键词）做第一阶段召回，再挂一个 CohereReranker 对候选结果做第二阶段重排。本文按 building blocks 目录中的前置要求，把这条完整路径从环境准备、配置、运行到结果判断走一遍。

准备条件

building blocks 的 README 明确列出了三项前置条件，缺一不可：

启动 Qdrant 向量数据库：运行 ./cookbook/scripts/run_qdrant.sh。该脚本（见 run_qdrant.sh）的实际内容是：

docker run -d \
  --name qdrant \
  -p 6333:6333 \
  -p 6334:6334 \
  -v $(pwd)/tmp/qdrant_storage:/qdrant/storage:z \
  qdrant/qdrant

注意两个副作用：容器名固定为 qdrant，重复执行前需要自行处理同名容器；数据持久化到仓库目录下的 tmp/qdrant_storage。

设置 OPENAI_API_KEY 环境变量（示例中的 embedder 和 Agent 模型都用 OpenAI）：

export OPENAI_API_KEY=your-key

如果要跑 reranking 示例，额外设置 COHERE_API_KEY 环境变量。

第一步：确认三种搜索类型，选定 hybrid

先理解 hybrid 搜索在 agno 中的定位。02_hybrid_search.py 的文档字符串说明 Knowledge 支持三种搜索类型：

Vector：语义相似度搜索，能找概念相关但用词不匹配的内容；
Keyword：全文搜索，快速、精确匹配术语；
Hybrid：向量 + 关键词结合，被标注为 "Recommended default"（推荐默认）。

该示例把同一份 PDF 分别灌入三个不同 collection，逐一对比三种搜索类型的回答效果：

from agno.agent import Agent
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.knowledge.knowledge import Knowledge
from agno.models.openai import OpenAIResponses
from agno.vectordb.qdrant import Qdrant
from agno.vectordb.search import SearchType

qdrant_url = "http://localhost:6333"
pdf_url = "https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf"

def create_knowledge(search_type: SearchType) -> Knowledge:
    return Knowledge(
        vector_db=Qdrant(
            collection="search_types_%s" % search_type.value,
            url=qdrant_url,
            search_type=search_type,
            embedder=OpenAIEmbedder(id="text-embedding-3-small"),
        ),
    )

if __name__ == "__main__":
    async def main():
        search_types = [
            (SearchType.vector, "Vector (semantic similarity)"),
            (SearchType.keyword, "Keyword (full-text search)"),
            (SearchType.hybrid, "Hybrid (vector + keyword)"),
        ]
        for search_type, description in search_types:
            knowledge = create_knowledge(search_type)
            # skip_if_exists=True avoids re-processing if run multiple times
            await knowledge.ainsert(url=pdf_url, skip_if_exists=True)

            agent = Agent(
                model=OpenAIResponses(id="gpt-5.2"),
                knowledge=knowledge,
                search_knowledge=True,
                markdown=True,
            )
            agent.print_response("How do I make pad thai?", stream=True)

    asyncio.run(main())

几个要点：

search_type 参数直接传给 Qdrant 构造函数，取值来自 agno.vectordb.search.SearchType；
三个搜索类型用不同的 collection 名（search_types_vector、search_types_keyword、search_types_hybrid），保证同一文档在三种模式下各自独立建索引，便于对照；
skip_if_exists=True 避免重复运行时重复处理同一 URL，多次实验时保留这个参数；
Agent 侧用 search_knowledge=True 启用 agentic RAG 模式。07_knowledge 的 README 区分了两种模式：add_knowledge_to_context=True（上下文自动注入）和 search_knowledge=True（Agent 持有搜索工具、自行决定何时搜索），后者是默认且推荐的方式。

运行方式（与 README 给出的示例一致）：

.venvs/demo/bin/python cookbook/07_knowledge/02_building_blocks/02_hybrid_search.py

运行后终端会按顺序打印三段输出，每段以 SEARCH TYPE: ... 分隔，分别展示 vector、keyword、hybrid 三种模式下对 "How do I make pad thai?" 的回答。你可以直接对比三段回答，确认 hybrid 模式在精确术语问题上的表现，再进入重排配置。

第二步：在 hybrid 召回之上挂 Cohere reranker

hybrid 解决的是"召回得更全"，重排解决的是"排得更准"。03_reranking.py 的文档字符串定义了 reranking 就是两阶段检索流程：

第一阶段用 vector/hybrid 搜索召回候选结果；
第二阶段由 reranker 模型按相关性对结果打分并重新排序。

文档说明这"especially for complex queries"能显著提升结果质量。目前支持四类 reranker：CohereReranker（标注 recommended）、SentenceTransformerReranker（本地 BAAI/bge 模型）、InfinityReranker（自托管）、BedrockReranker（AWS Bedrock）。本文按标题主线使用 Cohere。

完整配置只有几行核心差异——在 Qdrant 构造里加 reranker 参数，搜索类型保持 SearchType.hybrid：

from agno.agent import Agent
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.knowledge.knowledge import Knowledge
from agno.knowledge.reranker.cohere import CohereReranker
from agno.models.openai import OpenAIResponses
from agno.vectordb.qdrant import Qdrant
from agno.vectordb.search import SearchType

qdrant_url = "http://localhost:6333"

# Knowledge with hybrid search + Cohere reranking
knowledge = Knowledge(
    vector_db=Qdrant(
        collection="reranking_demo",
        url=qdrant_url,
        search_type=SearchType.hybrid,
        embedder=OpenAIEmbedder(id="text-embedding-3-small"),
        reranker=CohereReranker(model="rerank-multilingual-v3.0"),
    ),
)

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    knowledge=knowledge,
    search_knowledge=True,
    instructions=[
        "Always search your knowledge base before answering.",
        "Include sources in your response.",
    ],
    markdown=True,
)

if __name__ == "__main__":
    async def main():
        await knowledge.ainsert(
            url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf"
        )
        agent.print_response(
            "What are some good Thai dessert recipes?",
            stream=True,
        )

    asyncio.run(main())

配置说明：

reranker=CohereReranker(model="rerank-multilingual-v3.0") 与 search_type=SearchType.hybrid 配合，构成"hybrid 召回 → Cohere 重排"的两阶段链路；reranker 类从 agno.knowledge.reranker.cohere 导入；
这一步依赖第二步之外的 COHERE_API_KEY 环境变量，没设置会导致重排调用失败；
Agent 的 instructions 明确要求"回答前先搜索知识库"并"在回答中包含来源"，这是示例自带的行为约束，便于在验证时观察 Agent 是否真的走了检索链路。

运行：

.venvs/demo/bin/python cookbook/07_knowledge/02_building_blocks/03_reranking.py

结果如何判断

这两个示例没有断言式的自动校验，验证方式是观察终端流式输出：

02 示例：三段 SEARCH TYPE: ... 分隔的回答依次出现，重点看 hybrid 段对 "How do I make pad thai?" 的回答是否覆盖了具体做法步骤；
03 示例：终端打印 Hybrid search + Cohere reranking 标题后，Agent 流式输出对 "What are some good Thai dessert recipes?" 的回答。由于 instructions 要求包含来源，可以从回答中附带的来源信息确认检索链路生效。

示例输出内容依赖所用模型的实际回答，文档未给出固定期望文本，不要以某段具体措辞作为成功标准。

限制与可选分支

示例数据源是固定的公开 PDF（ThaiRecipes.pdf），collection 名（reranking_demo 等）和 embedder（text-embedding-3-small）沿用了示例原值；换成自己的文档时替换 ainsert 的 URL 和 collection 名即可，其余链路不变。
如果不想依赖 Cohere 服务，03 示例的文档字符串列出了替代 reranker：SentenceTransformerReranker（本地 BAAI/bge 模型，无需外部 API key）、InfinityReranker（自托管）、BedrockReranker（AWS），可对照 09_archive 中的 redis_db_with_cohere_reranker.py 等存档示例了解其他向量库上挂 reranker 的写法。
除搜索类型与 reranker 外，chunking、embedder 的调优分别在同目录的 01_chunking_strategies.py 和 06_embedders.py 中，属于独立的调优任务，不在本文范围内。