多模态数据检索是指向量数据库支持直接通过图文等多模态数据类型进行检索，且支持模态的组合，如文搜图，图搜图，图搜文+图等。
本页面主要介绍如何基于/index/search 接口实现多模态数据检索。

• 从控制台选择了从向量化开始的数据库类型，并在创建数据集时配置了向量化字段；或通过 create_collection 接口创建数据集时，通过设置 vectorize 参数配置了 Collection 的向量化功能。
• 通过 upsert_data 接口写入数据时，已写入 text或image 类型的字段名称和字段值。
• Index 创建时，已创建 vector_index 向量索引。

最简洁的多模态检索可通过配置search接口下的 order_by_raw 和 need_instruction 子参数实现，输入文本或图片tos链接，检索出与之最相似的数据。请求参数如下：

在下面的示例中，假设多模态数据集下存放了如下 10 条数据。每条数据都有 id, picture,introduction,name,city, salary这几个字段，其中picture为image类型的字段，introduction为text类型的字段。

{"id": "1", "name": "Alice", "city": "New York", "salary": 85000, "picture": "tos://example-bucket/pic1.jpg", "introduction": "Alice 是一位居住在 New York 的专业人士，年薪为 $85,000。"}
{"id": "2", "name": "Bob", "city": "San Francisco", "salary": 120000, "picture": "tos://example-bucket/pic2.jpg", "introduction": "Bob 是一位居住在 San Francisco 的专业人士，年薪为 $120,000。"}
{"id": "3", "name": "Charlie", "city": "Chicago", "salary": 78000, "picture": "tos://example-bucket/pic3.jpg", "introduction": "Charlie 是一位居住在 Chicago 的专业人士，年薪为 $78,000。"}
{"id": "4", "name": "Diana", "city": "London", "salary": 95000, "picture": "tos://example-bucket/pic4.jpg", "introduction": "Diana 是一位居住在 London 的专业人士，年薪为 $95,000。"}
{"id": "5", "name": "Ethan", "city": "Toronto", "salary": 91000, "picture": "tos://example-bucket/pic5.jpg", "introduction": "Ethan 是一位居住在 Toronto 的专业人士，年薪为 $91,000。"}
{"id": "6", "name": "Fiona", "city": "Sydney", "salary": 104000, "picture": "tos://example-bucket/pic6.jpg", "introduction": "Fiona 是一位居住在 Sydney 的专业人士，年薪为 $104,000。"}
{"id": "7", "name": "George", "city": "Berlin", "salary": 83000, "picture": "tos://example-bucket/pic7.jpg", "introduction": "George 是一位居住在 Berlin 的专业人士，年薪为 $83,000。"}
{"id": "8", "name": "Hannah", "city": "Paris", "salary": 98000, "picture": "tos://example-bucket/pic8.jpg", "introduction": "Hannah 是一位居住在 Paris 的专业人士，年薪为 $98,000。"}
{"id": "9", "name": "Ian", "city": "Tokyo", "salary": 89000, "picture": "tos://example-bucket/pic9.jpg", "introduction": "Ian 是一位居住在 Tokyo 的专业人士，年薪为 $89,000。"}
{"id": "10", "name": "Julia", "city": "Singapore", "salary": 115000, "picture": "tos://example-bucket/pic10.jpg", "introduction": "Julia 是一位居住在 Singapore 的专业人士，年薪为 $115,000。"}

• 输入文本检索：

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-vikingdb.volces.com/api/index/search \
  -d '{
    "collection_name": "test_name",    //用于检索的集合的名称
    "index_name": "index_test",    //用于检索的索引名称
    "search": {
        "order_by_raw":{
            "text":"hello" 
        }
        }
}'

• 输入图片检索

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-vikingdb.volces.com/api/index/search \
  -d '{
    "collection_name": "test_name",    //用于检索的集合的名称
    "index_name": "index_test",    //用于检索的索引名称
    "search": {
        "order_by_raw":{
            "image":"tos://best-practice-pic-search-tos/pic_search_1000_images/003bd60fa9.jpg}" 
        }
        }
}'

• 输入图文检索：

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-vikingdb.volces.com/api/index/search \
  -d '{
    "collection_name": "test_name",    //用于检索的集合的名称
    "index_name": "index_test",    //用于检索的索引名称
    "search": {
        "order_by_raw":{
            "text":"hello" ,
            "image":"tos://best-practice-pic-search-tos/pic_search_1000_images/003bd60fa9.jpg}" 
        }
        }
}'

执行成功返回示例：

{
  "code": 0,
  "data": [
    [
      {
        "fields": {
          "city": "New York",
          "id": 1,
          "name": "Alice",
          "salary": 85000,
          "picture": "tos://example-bucket/pic1.jpg",
          "introduction": "Alice 是一位居住在 New York 的专业人士，年薪为 $85,000。"
        },
        "id": 1,
        "score": 1.0002950429916382
      },
      {
        "fields": {
          "city": "San Francisco",
          "id": 2,
          "name": "Bob",
          "salary": 120000,
          "picture": "tos://example-bucket/pic2.jpg",
          "introduction": "Bob 是一位居住在 San Francisco 的专业人士，年薪为 $120,000。"
        },
        "id": 2,
        "score": -0.017884135246276855
      }
    ],
    [
      {
        "fields": {
          "city": "San Francisco",
          "id": 2,
          "name": "Bob",
          "salary": 120000,
          "picture": "tos://example-bucket/pic2.jpg",
          "introduction": "Bob 是一位居住在 San Francisco 的专业人士，年薪为 $120,000。"
        },
        "id": 2,
        "score": 0.9990343451499939
      },
      {
        "fields": {
          "city": "New York",
          "id": 1,
          "name": "Alice",
          "salary": 85000,
          "picture": "tos://example-bucket/pic1.jpg",
          "introduction": "Alice 是一位居住在 New York 的专业人士，年薪为 $85,000。"
        },
        "id": 1,
        "score": -0.018528103828430176
      }
    ]
  ],
  "message": "success",
  "request_id": "02174781958394600000000000000000000ffff0a00744bebcae7"
}

如果在创建索引时划分了子索引 partition，并且查询目标可以具体到其中的一个 partition，可以在检索时指定在特定partiton中进行检索，从而减少扫描的数据量，提高检索速度。
在基础向量检索的基础上，通过配置search接口下的partition参数可以实现对特定子索引的检索：

假设在创建索引时设置了city字段为子索引字段，根据city字段的取值将数据集划分成了不同的子数据集，现在想对名为London的partiton进行检索，可以通过如下方式实现：

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-vikingdb.volces.com/api/index/search \
  -d '{
    "collection_name": "test_name",    //用于检索的集合的名称
    "index_name": "index_test",    //用于检索的索引名称
    "search": {
        "order_by_raw":{
            "text":"hello" ,
            "image":"tos://best-practice-pic-search-tos/pic_search_1000_images/003bd60fa9.jpg}" 
        },
        "partiton": "London"
        }
}'

检索过滤是指在向量相似度检索过程中，结合结构化的元数据（如数值、布尔值、字符串等）对候选数据进行筛选的过程。这种过滤可以提高检索结果的相关性和精度。
检索过滤为可选能力，需要配合基础的向量检索能力使用，可以配置一种或多种检索过滤方式。

标量过滤

标量过滤检索是指在向量数据库中，同时使用向量检索和标量检索两种方法进行检索。在标量过滤检索中，使用向量检索来匹配向量的相似度，同时使用标量检索来匹配向量的标量值。
在基础向量检索的基础上，可以通过配置search接口下的filter参数来实现对检索结果的标量过滤，详细的使用方法参考标量过滤。

主键过滤

主键过滤是指在向量检索时，仅对指定主键值数据执行近邻搜索，从而有效缩小检索范围并提升性能与准确度
在基础向量检索的基础上，可以通过配置search接口下的 primary_key_in/primary_key_not_in 子参数对特定主键值的数据进行检索，详细的使用方法参考主键过滤。

后置过滤

后置过滤是 VikingDB 提供的一种检索后处理能力，用于在向量召回之后，对候选数据进行进一步的过滤和优化，确保最终返回的搜索结果更加精准、高效。VikingDB 提供了以下几种后置过滤能力：

• **正则表达式匹配：**利用正则表达式对字符串字段进行模式匹配的过滤方式。适用于需要进行复杂字符串匹配的场景。
• **关键词匹配：**一种基于字符串字段内容进行子串匹配的过滤方式。它允许用户查找字段中包含特定关键词或字符的数据记录。
• **频控：**用于保证一次召回的结果中, 一个特定取值出现的总数不超过特定值。

在基础向量检索的基础上，可以通过配置search接口下的 post_process_ops和post_process_input_limit配置后置过滤能力，详细的使用方法详见后置处理算子。

输出字段选择

通过配置search接口下的 output_fields子参数可以限制检索结果只返回指定的字段:

例如希望在返回结果中只保留“name”字段：

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-vikingdb.volces.com/api/index/search \
  -d '{
        "collection_name": "test_name",
        //用于检索的集合的名称
        "index_name": "index_test",
        //用于检索的索引名称
        "search": {
                "order_by_raw":{
                    "text":"hello" ,
                    "image":"tos://best-practice-pic-search-tos/pic_search_1000_images/003bd60fa9.jpg}" 
        },
                "output_fields": ['name']
        }
}'

分页查询

分页能力通过在检索请求中指定 offset 和 limit参数，将结果分批返回，在降低单次响应延迟的同时便于前端交互和资源管理

例如指定返回10个结果：

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-vikingdb.volces.com/api/index/search \
  -d '{
        "collection_name": "test_name",
        //用于检索的集合的名称
        "index_name": "index_test",
        //用于检索的索引名称
        "search": {
                "order_by_raw":{
                    "text":"hello" ,
                    "image":"tos://best-practice-pic-search-tos/pic_search_1000_images/003bd60fa9.jpg}" 
        },
                "limit": 2, # 每页返回 2 条结果
                "offset": 4 # 跳过前 4 条结果,获取第三页结果
        }
}'

状态码说明

请求消息

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-vikingdb.volces.com/api/index/search \
  -d '{
    "collection_name": "test_name",    //用于检索的集合的名称
    "index_name": "index_test",    //用于检索的索引名称
    "search": {
        "order_by_raw":{
            "text":"hello" ,
            "image":"tos://best-practice-pic-search-tos/pic_search_1000_images/003bd60fa9.jpg}" 
        }, 
        "partiton": "London"，//指定partition，
        "filter": {
                        "op": "range",
                        "field": "salary",
                        "gte": 10000
                }，
         "post_process_ops": {
                        "op": "string_contain",
                        "field": "name",
                        "pattern": "s"
                }，
          "output_fields": ['name']，
          "limit": 2, # 每页返回 2 条结果
          "offset": 4 # 跳过前 4 条结果,获取第三页结果
        }
}
}'

响应消息

执行成功返回：

HTTP/1.1 200 OK
Content-Length: 43
Content-Type: application/json
 
{
    "code":0,
    "msg":"search success",
    "request_id":"021695029537650fd001de666660000000000000000000230da93",
    "data": [
        [
            {
                "id": 1,
                "score": 0.99,
                "fields": {
                    "name": "Alice"
                } 
            },
            {
                "id": 2,
                "score": 0.98,
                "fields": {
                    "name": "Fiona"
                } 
            }
        ],
        [
            {
                "id": 9,
                "score": 0.95,
                "fields": {
                    "name": "Charlie"
                } 
            },
            {
                "id": 8,
                "score": 0.84,
                "fields": {
                    "name": "Ethan"
                } 
            }            
        ]
    ]
}

执行失败返回：

HTTP/1.1 400 OK
Content-Length: 43
Content-Type: application/json
 
{"code":1000008, "msg":"index not exist","request_id":"021695029537650fd001de666660000000000000000000230da93"}