---
title: "全模态知识库检索"
method: POST
path: "/zrag/retrieval/retrieve"
tags: ["知识库 API"]
---

# 全模态知识库检索

`POST /zrag/retrieval/retrieve`

用于检索全模态知识库，支持文本、图片、视频等多模态输入检索，支持向量检索、关键词检索、混合检索，支持查询重写、重排、QA干预等高级功能。点击 **Try it** 按钮可快速试用。

## Request body

- ZragRetrieveRequest
  - `multimodal` boolean — 是否走多模态路径检索，默认值为true
  - `knows` object[], required — 查询的知识库列表
    - `id` string, required — 知识库ID
    - `doc_ids` string[] — 知识库下的文档ID列表
  - `query` string — 文本查询内容，与多模态查询内容必须传入其中之一
  - `multimodal_parts` object[] — 多模态查询内容，与文本查询内容必须传入其中之一
    - `type` 'image_url', required — 仅支持图片类型：image_url
    - `url` string, required — 图片URL链接
  - `top_k` integer — 最终召回数量，默认为8
  - `top_n` integer — 初始召回数量，默认为10
  - `recall_method` 'embedding' | 'keyword' | 'mixed' — 文本检索方式：embedding（向量检索）、keyword（关键词检索）、mixed（混合检索）
  - `recall_ratio` number — 混合检索中向量检索的权重，取值范围0~1
  - `enable_rerank` boolean — 是否开启重排，默认不开启
  - `enable_rewrite` boolean — 是否开启查询重写，可配合messages参数实现多轮对话改写，默认不开启
  - `enable_expansion` boolean — 是否开启扩召，默认不开启
  - `similarity_threshold` number — 相似度阈值，低于该阈值的切片会被过滤
  - `messages` object[] — 当前对话消息列表，用于多轮对话改写
    - `role` 'user' | 'assistant', required
    - `content` string, required — 消息内容，仅支持文本
  - `search_filters` object — 过滤条件
    - `index_types` object[] — 索引列表
      - `know_id` string, required — 知识库ID
      - `index_type_id` integer, required — 索引ID
    - `tags` object[] — 标签列表
      - `tag_id` string, required — 标签ID
      - `value_type` 'fixed' | 'ref', required — 固定值：fixed，引用变量：ref
      - `filter_type` 1 | 2 | 3 | 4, required — 过滤类型：1: >=，2: <=，3: 包含，4: 不包含
      - `filter_value` string, required — 日期/文本/引用值
      - `multiple_value` string[], required — 选项值列表
    - `qa_intervention` object — QA干预配置
      - `qa_similarity_threshold` number, required — QA干预相似度阈值
      - `qa_intervention_ids` string[], required — QA知识库ID列表

## Response `200`

业务处理成功

- ZragRetrieveResponse
  - `data` object
    - `contents` object[] — 检索结果列表
      - `id` string — 切片ID（UUID）
      - `know_id` string — 知识库ID
      - `doc_id` string — 文档ID
      - `text` string — 文本内容
      - `medias` object[] — 文本中的媒体文件
        - `id` string — 图片ID
        - `url` string — 图片URL
        - `description` string — 图片描述
      - `image_url` object — 图像URL
        - `url` string — URL
      - `video_url` object — 视频URL
        - `url` string — URL
      - `index` integer — 召回位次
      - `score` number — 召回分数
      - `rerank_index` integer — 重排位次
      - `rerank_score` number — 重排分数
      - `metadata` object — 元数据
        - `doc_type` string — 文档类型，如 pdf、docx、jpeg、png、mp4、mp3 等
        - `doc_name` string — 文档名称
        - `doc_url` string — 文档URL
        - `index` integer — 切片下标
        - `page_index` integer — 文档页码
        - `clip_index` integer — 视频切片下标
        - `start_time` integer — 首帧时间戳
        - `end_time` integer — 尾帧时间戳
        - `duration` integer — 视频切片时长
        - `frames` string[] — 关键帧列表
    - `rewritten_query` object — 查询重写结果
      - `original_query` string — 原始查询
      - `multi_queries` string[] — 备选查询列表
    - `elapsed_ms` integer — 请求耗时（毫秒）
    - `total_tokens` integer — 消耗的token数量
    - `request_id` string — 请求ID
  - `code` integer — 错误码，200为成功
  - `message` string — 错误信息

## Other responses

- `default` — 请求失败。

---

[API](https://skmtc.net/bigmodel/apis/zhipu-ai-api.md) · [All operations](https://skmtc.net/bigmodel/apis/zhipu-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bigmodel/zhipu-ai-api/revisions/37de2d7b73de/schema)