【AskAI系列课程】：P3.Agno从阿里云百炼知识库中检索知识库片段并回答用户问题

这是【AskAI系列课程】的第 3 课：实现 Bailian retriever 并将其集成到 Agno Agent 中，让 AI 助手能够基于知识库内容（我的网站文档和博客内容）回答用户问题。

演示效果

我有一篇博客是关于使用 OpenLayers + 高德瓦片源实现旅游足迹地图，当我提问："怎么实现足迹地图？"时，AI 根据我的网站博客内容回答了问题。

点开工具调用信息我们可以看到查询知识库返回的详细片段，这些片段被 LLM 作为上下文信息整合到回答中。

真正集成到我个人网站的实现请看本系列P4课程文章将AI助手集成到Astro网站前端。

为什么需要自定义检索器？

在上一课中，我们成功将网站文档上传到了阿里云百炼知识库。阿里云百炼本身已经提供了完整的 RAG 能力：

• 使用 embedding 模型对文档进行分块和向量化
• 提供向量检索和关键词检索能力
• 支持检索结果的重排序和优化

但是，Agno 框架目前不支持阿里云百炼作为官方知识库。

所以我们需要参考官方文档 - Implementing a Custom Retriever实现自定义检索器来解决这个适配问题：

1. 调用百炼检索 API获取相关文档片段
2. 包装成 Agno 兼容的格式
3. 集成到 Agent 的知识检索流程

这样既能享受百炼成熟的 RAG 能力，又能在 Agno 框架中使用，这也是演示如何让 Agno 适配非官方支持的知识库的典型案例。

核心功能详解

检索器的设计思路

我们要实现的检索器需要满足两个关键需求：

1. 与百炼 API 对接：调用百炼的检索接口，获取相关文档片段
2. 符合 Agno 规范：返回 Agno Agent 期望的数据格式

基于这个思路，我设计了一个两层架构：

• 底层检索函数 ：retrieve_from_bailian() - 纯粹的百炼 API 调用
• 适配器函数 ：smart_bailian_retriever() - 包装成 Agno 兼容格式

数据流转详解

让我们深入看看数据在各个环节是如何流转的：
用户 Agno Agent smart_bailian_retriever 百炼检索API 知识库 提问："怎么实现足迹地图？" 调用 knowledge_retriever retrieve_from_bailian(query) 向量检索相关文档 返回匹配的文档片段 原始检索结果 格式化为 LLM 更易读的格式 返回格式化结果 基于检索结果生成回答 返回最终答案 用户 Agno Agent smart_bailian_retriever 百炼检索API 知识库

核心代码实现

现在让我们深入关键的代码实现。整个实现分为两个核心文件：检索器实现和 Agent 集成。

1. 百炼检索器实现

首先是纯粹的百炼 API 调用实现（bailian/retriever.py）：

def retrieve_from_bailian(query: str) -> List[Dict[str, Any]]:
    """检索知识库内容。
    返回检索结果列表，每个元素为字典，包含 content 和 metadata 字段。
    """
    workspace_id = os.environ.get("ALIBABA_CLOUD_BAILIAN_WORKSPACE_ID")
    index_id = os.environ.get("ALIBABA_CLOUD_BAILIAN_KB_INDEX_ID")

    client = create_client()

    # 构建检索请求
    retrieve_request = bailian_20231229_models.RetrieveRequest(
        query=query,
        enable_reranking=False,  # 是否启用重排序
        index_id=index_id,
    )

    try:
        result = client.retrieve_with_options(
            workspace_id,
            retrieve_request,
            headers,
            runtime,
        )

        # 解析返回结果
        body = getattr(result, "body", None)
        success = getattr(body, "success", False)
        data = getattr(body, "data", None)
        nodes = getattr(data, "nodes", None)

        if not success or not nodes:
            raise RuntimeError("资料库查询失败")

        # 格式化检索结果
        docs: List[Dict[str, Any]] = []
        chunk_limit = int(os.environ.get("KB_CHUNK_COUNT", "5"))

        for node in list(nodes)[:chunk_limit]:
            md = get_attr(node, "metadata", {}) or {}
            content = get_attr(node, "text", "") or ""
            doc_name = get_attr(md, "doc_name", "")
            score = get_attr(node, "score", None)

            docs.append({
                "content": content,
                "metadata": {
                    "document_name": doc_name,
                    "score": float(score) if isinstance(score, (int, float)) else None
                },
            })
        return docs
    except Exception as e:
        print(f"Bailian retriever failed: {e}")
        return []

关键技术要点：

• 使用环境变量管理配置，便于部署和测试
• 支持通过 KB_CHUNK_COUNT 控制返回片段数量
• 统一的错误处理，避免检索失败影响整个对话
• 标准化的返回格式，包含内容和元数据

2. Agno 适配器实现

接下来是 Agno Agent 的适配器实现（fastcar_os.py）：

def smart_bailian_retriever(
    query: str,
    agent: Optional[AgnoAgent] = None,
    num_documents: int = 10,
    **kwargs,
) -> Optional[List[Dict[str, Any]]]:
    """
    基于阿里云百炼知识库的自定义 knowledge_retriever（Agno v2）。
    """
    try:
        return retrieve_from_bailian(query)
    except Exception as e:
        print(f"Bailian retriever failed: {e}")
        return None

这个适配器函数的作用是：

• 接口适配 ：符合 Agno knowledge_retriever 的函数签名
• 异常处理：确保检索失败时不会中断对话
• 参数兼容：支持 Agno 传递的额外参数

3. Agent 集成配置

最后是将检索器集成到 Agno Agent 中：

assistant = Agent(
    name="Assistant",
    model=OpenAILike(
        id=os.getenv("ARK_BIG_THINKING_MODEL"),
        api_key=os.getenv("ARK_API_KEY"),
        base_url=os.getenv("ARK_BASE_URL"),
    ),
    instructions=["你是我个人网站的AI助手，请根据用户的问题给出回答。"],
    markdown=True,
    db=db,
    # 关键配置：接入百炼知识库
    knowledge_retriever=smart_bailian_retriever,
    search_knowledge=True,  # 启用知识检索
)

集成要点：

• knowledge_retriever 参数指定自定义检索函数
• search_knowledge=True 启用知识检索功能
• Agent 会在需要时自动调用检索器获取相关信息

环境配置与部署

环境变量配置

在 .env 文件中添加必要的配置：

# 阿里云百炼配置
ALIBABA_CLOUD_ACCESS_KEY_ID=你的AccessKey
ALIBABA_CLOUD_ACCESS_KEY_SECRET=你的SecretKey
ALIBABA_CLOUD_BAILIAN_WORKSPACE_ID=你的WorkspaceId
ALIBABA_CLOUD_BAILIAN_KB_INDEX_ID=你的IndexId

# 可选：控制检索片段数量
KB_CHUNK_COUNT=5

# LLM 模型配置
ARK_BIG_THINKING_MODEL=你的模型ID
ARK_API_KEY=你的API密钥
ARK_BASE_URL=你的API地址

启动服务

# 安装依赖
./setup.sh

# 启动 Agent 服务
python fastcar_os.py

服务启动后，Agent 就具备了基于知识库(我的网站文档和博客内容)回答问题的能力。

检索效果验证

检索流程监控

当用户提问时，可以在控制台看到检索过程：

DEBUG ====================================== user ======================================
DEBUG 怎么生成足迹地图
DEBUG =================================== assistant ====================================
DEBUG 我来帮您搜索一下关于生成足迹地图的相关信息。
DEBUG Tool Calls:
        - ID: 'search_knowledge_base:0'
          Name: 'search_knowledge_base'
          Arguments: 'query: 生成足迹地图'
DEBUG ***********************************  METRICS  ************************************
DEBUG * Tokens:                      input=138, output=31, total=169
DEBUG * Duration:                    1.6800s
DEBUG * Tokens per second:           18.4528 tokens/s
DEBUG ***********************************  METRICS  ************************************
DEBUG Running: search_knowledge_base(query=生成足迹地图)
>>>>>>>>>>>>>>>>>>> 开始检索：生成足迹地图 检索 <<<<<<<<<<<<<<<<
DEBUG Time to get references: 0.9020s
DEBUG ====================================== tool ======================================
DEBUG Tool call Id: search_knowledge_base:0
DEBUG [
        {
          "content":
      "[旅游足迹地图演示](https://fastcar.fun/about#travel)我的主页：https://fastcar.fun你可以在我的关
      于页面看到这个旅游足迹地图的实际效果，地图上标记了我去过的城市和想去的地方。\n功能点详解\n技术选
      型考虑在实现这个功能时，我面临几个技术选型的问题：地图库选择：Google Maps
      API：需要翻墙，在国内访问不稳定百度地图 API：需要申请 key，有使用限制高德地图 API：同样需要申请
      keyOpenLayers + 开放瓦片源：免费、灵活、无需 key最终选择 OpenLayers
      是因为它是一个功能强大的开源地图库，支持多种瓦片源，而且可以直接使用高德地图的公开瓦片服务，无需
      申请 API
      key。瓦片源选择：\n高德地图提供了公开的瓦片服务，支持多种样式：标准地图：`style=8`（亮色主题）暗
      色地图：`style=7`（暗色主题）卫星图：`style=6`路网图：`style=1`这些瓦片源都支持中文标注，非常适
      合国内用户使用。",
          "metadata": {
            "document_name": "blog_travel-map-openlayers-amap",
            "score": 0.7284883209342737
          }
        },
        {
          "content": "通过使用 OpenLayers +
      高德瓦片源，我成功实现了一个功能完整的旅游足迹地图。这个方案的主要优势：技术优势：无需申请 API
      key，降低使用门槛支持自定义样式和交互高德地图在国内访问速度快，中文支持好OpenLayers
      功能强大，扩展性好功能特色：双主题自动切换，与网站整体风格保持一致直观的标记系统，清晰区分已访问
      和愿望清单响应式设计，移动端体验良好交互弹窗提供详细信息展示后续改进方向：添加路线规划功能，连接
      相邻的旅游点支持照片上传，为每个地点添加旅游照片增加统计功能，显示旅游里程、访问城市数量等支持数
      据导入导出，方便备份和分享添加搜索功能，快速定位特定地点集成天气信息，显示各地实时天气这个旅游足
      迹地图不仅满足了我个人记录旅游经历的需求，也为网站访客提供了一个了解我旅游足迹的有趣方式。通过开
      源的技术栈实现，也为其他开发者提供了一个可参考的实现方案。",
          "metadata": {
            "document_name": "blog_travel-map-openlayers-amap",
            "score": 0.7284883209342737
          }
        },

然后前端也可以看到如演示效果章节所示的对话效果。

简单总结

通过这一课的实现，我们成功构建了一个完整的 RAG 检索系统：

核心价值

• 知识库驱动：AI 回答基于真实的文档内容，准确性大幅提升
• 架构清晰：分层设计便于维护和扩展
• 集成简单：只需几行代码就能为 Agent 添加知识检索能力

技术亮点

• 使用阿里云百炼的成熟检索能力，避免重复造轮子
• 通过适配器模式实现与 Agno 框架的无缝集成
• 完善的错误处理确保系统稳定性

后续方向

下一课我们将探讨如何将这个 Agent 接入到网站前端，实现完整的 AskAI 功能，让访客能够直接在网站上与 AI 助手对话。

参考资料

源码：https://github.com/Match-Yang/fastcar-web

我的个人网站：https://www.fastcar.fun/