DocsICP FilingConsole
Documentation
Home Page Vector Retrieval Service for Milvus Developer Reference API Reference（Knowledge Base） API catalog SearchKnowledgeBase

SearchKnowledgeBase

Updated at:
Copy as MD
My Favorites

Searches a specified knowledge base based on a query or an image.

Operation description

Searches a specified knowledge base based on a query or an image. For the version, use the display name DRAFT, LATEST_PUBLISHED, or vN. Pass tag filter conditions based on the actual operators used by the backend.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

No authorization for this operation. If you encounter issues with this operation, contact technical support.

Request syntax

POST /api/v1/knowledge-bases/{knowledgeBaseId}/search HTTP/1.1

Path Parameters

Parameter

Type

Required

Description

Example
knowledgeBaseId

string

No

The knowledge base ID.

kd-620ad908ec651

Request parameters

Parameter

Type

Required

Description

Example
body

object

No

The retrieval request.

documentIds

array

No

The list of document IDs.

string

No

The document ID.

539ddb688fe811f182f637422a0713b5
enableKnowledgeGraph

boolean

No

Specifies whether to enable the knowledge graph.

false
evidencePageToken

string

No

Optional. Returned conditionally. This parameter can be passed only when includeWiki is set to true. Omit this parameter for the first evidence page. For subsequent pages, pass the evidenceNextToken value from the previous page as is. The candidate pool, subject, parameters, and page size are fixed and expire after 5 minutes without renewal. If the token expires, a 409 error is returned and no automatic re-search is performed. The pageNumber parameter only controls the legacy results. Constraints: {"minLength":1,"maxLength":4096}.

example-opaque-next-token
image

object

No

The image retrieval input.

base64

string

No

The Base64-encoded image.

data:image/png;base64,iVBORw0KGgoAAA...
objectKey

string

No

The object key of the image.

uploaded/invoice.png
url

string

No

The URL of the image.

https://example.com/invoice.png
includeWiki

boolean

No

Optional. Returned conditionally. Added for compatibility. Default value: false. If set to true, the unified evidenceResults are additionally returned, and Wiki content is not presented as original text. Constraints: {"default":false}.

true
pageNumber

integer

No

The page number.

1
pageSize

integer

No

The number of items per page.

5
query

string

No

The search query.

What is the tax amount on the invoice?
rerankModelId

integer

No

The rerank model ID.

123
rerankModelName

string

No

The name of the rerank model activated for the tenant. If both rerankModelId and this parameter are specified, this parameter takes precedence.

qwen3-rerank
retrievalConfig

object

No

The retrieval configuration.

candidateCount

integer

No

The number of recalled candidates.

5
enableQueryExpansion

boolean

No

Specifies whether to enable query expansion.

true
minScore

number

No

The minimum relevance score.

0.2
semanticWeight

number

No

The weight of semantic relevance.

0.5
translationLanguages

array

No

The list of translation languages.

string

No

The language.

English
tagFilter

object

No

The tag filter.

conditions

array<object>

No

The list of tag conditions.

object

No

The tag condition.

field

string

No

The tag field.

category
op

string

No

The operator.

in
value

any

No

The tag value.

invoice
relation

string

No

The logical relation between conditions.

or
version

string

No

The knowledge base version.

v1

Response elements

Element

Type

Description

Example

object

The search results.

accessDeniedDetail

string

The details of the access denial.

{"PolicyType":"AccountLevelIdentityBasedPolicy","NoPermissionType":"ImplicitDeny","AuthAction":"milvusknowledgebase:SearchKnowledgeBase"}
code

integer

The returned status code.

0
evidenceNextToken

string

The cursor for the next page of evidence. This parameter is optional and conditionally returned. It is always returned when includeWiki is set to true. The value is null for the last page. This parameter is not used for legacy results pagination. Null values are allowed. The not-equal-to condition can be omitted. Constraints: {"minLength":1,"maxLength":4096}.

example-opaque-next-token
evidenceResults

array<object>

The current page of unified and merged evidence results. This parameter is optional and conditionally returned. It is returned only when includeWiki is set to true. Constraints: {"minItems":0,"maxItems":100}.

[{"evidenceId":"wiki_section_page_1_sec_1_rev_7","kind":"wiki_section","knowledgeBaseId":"example_kb","documentId":null,"chunkId":null,"pageId":"page_1","sectionId":"sec_1","entityId":null,"relationId":null,"revisionId":"rev_7","batchId":"batch_7","title":"Warranty instructions","content":"The warranty period for Product A is 18 months.","score":0.62,"sourceRefs":[{"documentId":"doc_manual","chunkId":"chunk_1","sourceRevisionId":"source_rev_7","version":"DRAFT"}],"sourceRefCount":1,"sourceRefsTruncated":false,"sourceTaskId":"11111111111111111111111111111111"}]

array<object>

The structured object for an evidence result item. This parameter is required and always returned. Conditional requirements and cross-field rules are validated by the backend. Refer to the operation description and the full contract for details.

{"evidenceId":"wiki_section_page_1_sec_1_rev_7","kind":"wiki_section","knowledgeBaseId":"example_kb","documentId":null,"chunkId":null,"pageId":"page_1","sectionId":"sec_1","entityId":null,"relationId":null,"revisionId":"rev_7","batchId":"batch_7","title":"Warranty instructions","content":"The warranty period for Product A is 18 months.","score":0.62,"sourceRefs":[{"documentId":"doc_manual","chunkId":"chunk_1","sourceRevisionId":"source_rev_7","version":"DRAFT"}],"sourceRefCount":1,"sourceRefsTruncated":false,"sourceTaskId":"11111111111111111111111111111111"}
batchId

string

The ID of the processing batch. This parameter is required and always returned. Null values are allowed, and the semantics of null values follow the field description. The not-equal-to condition can be omitted. Constraints: {"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"}.

null
chunkId

string

The ID of the processing batch. This parameter is required and always returned. Null values are allowed, and the semantics of null values follow the field description. The not-equal-to condition can be omitted. Constraints: {"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"}.

null
content

string

The readable evidence text within the budget. This parameter is required and always returned. Constraints: {"maxLength":65535}.

The warranty period for Product A is 18 months
documentId

string

The ID of the processing batch. This parameter is required and always returned. Null values are allowed, and the semantics of null values follow the field description. The not-equal-to condition can be omitted. Constraints: {"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"}.

null
entityId

string

The ID of the processing batch. This parameter is required and always returned. Null values are allowed, and the semantics of null values follow the field description. The not-equal-to condition can be omitted. Constraints: {"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"}.

null
evidenceId

string

The opaque business ID of the evidence generated by the server. This parameter is required and always returned. The system validates the ownership and does not accept arbitrary paths. Constraints: {"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"}.

wiki_section_page_1_sec_1_rev_7
kind

string

The actual object type of the evidence. This parameter is required and always returned. Constraints: {"enum":["raw","wiki_page","wiki_section","graph_fact"],"maxLength":64}.

Valid values:

  • raw
  • wiki_page
  • wiki_section
  • graph_fact

wiki_section
knowledgeBaseId

string

The opaque business ID of the evidence generated by the server. This parameter is required and always returned. The system validates the ownership and does not accept arbitrary paths. Constraints: {"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"}.

example_kb
pageId

string

The ID of the processing batch. This parameter is required and always returned. Null values are allowed, and the semantics of null values follow the field description. The not-equal-to condition can be omitted. Constraints: {"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"}.

page_1
relationId

string

The ID of the processing batch. This parameter is required and always returned. Null values are allowed, and the semantics of null values follow the field description. The not-equal-to condition can be omitted. Constraints: {"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"}.

null
revisionId

string

The opaque business ID of the evidence generated by the server. This parameter is required and always returned. The system validates the ownership and does not accept arbitrary paths. Constraints: {"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"}.

example_value
score

number

The finite numerical value used for unified ranking. This parameter is required and always returned. For hybrid search, it represents the relevance of the existing Dealer.rerank. For rerank, it represents the text and model hybrid relevance of the existing Dealer.rerank_by_model, based on semanticWeight and rank features, rather than relevance probability. The minScore is applied according to the existing unified scoring rules. The value can be null for non-ranking factual evidence. Null values are allowed. The not-equal-to condition can be omitted.

0.62
sectionId

string

The ID of the processing batch. This parameter is required and always returned. Null values are allowed, and the semantics of null values follow the field description. The not-equal-to condition can be omitted. Constraints: {"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"}.

sec_1
sourceRefCount

integer

The total number of source chunk references. This parameter is required and always returned. Authentication is performed based on the full set. Constraints: {"minimum":1,"maximum":9223372036854775807}.

1
sourceRefs

array<object>

The actual supported sources. This parameter is required and always returned. Constraints: {"minItems":1,"maxItems":1000}.

[{"documentId":"doc_manual","chunkId":"chunk_1","sourceRevisionId":"source_rev_7","version":"DRAFT","contentHash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}]

object

The structured object for a source reference. This parameter is required and always returned.

{"documentId":"example_value","chunkId":"example_value","sourceRevisionId":"example_value","version":"DRAFT","contentHash":"0000000000000000000000000000000000000000000000000000000000000000"}
chunkId

string

The opaque business ID of the evidence generated by the server. This parameter is required and always returned. The system validates the ownership and does not accept arbitrary paths. Constraints: {"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"}.

example_value
documentId

string

The opaque business ID of the evidence generated by the server. This parameter is required and always returned. The system validates the ownership and does not accept arbitrary paths. Constraints: {"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"}.

example_value
documentName

string

The name of the document. This parameter is optional and conditionally returned. It is returned only after authorization. Constraints: {"maxLength":1024}.

example_value
mediaEndMs

integer

The end time of the media in milliseconds. This parameter is optional and conditionally returned. Null values are allowed, and the semantics of null values follow the field description. The not-equal-to condition can be omitted. Constraints: {"minimum":0,"maximum":9223372036854775807}.

0
mediaStartMs

integer

The end time of the media in milliseconds. This parameter is optional and conditionally returned. Null values are allowed, and the semantics of null values follow the field description. The not-equal-to condition can be omitted. Constraints: {"minimum":0,"maximum":9223372036854775807}.

0
pageNumber

integer

The page number. This parameter is optional and conditionally returned. Null values are allowed, and the semantics of null values follow the field description. The not-equal-to condition can be omitted. Constraints: {"minimum":1,"maximum":9223372036854775807}.

1
sourceRevisionId

string

The opaque business ID of the evidence generated by the server. This parameter is required and always returned. The system validates the ownership and does not accept arbitrary paths. Constraints: {"minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$"}.

example_value
version

string

The display name of the version. This parameter is required and always returned. The system does not fall back to the draft version if the specified version is invalid or unavailable. Constraints: {"maxLength":64,"pattern":"^(DRAFT|LATEST_PUBLISHED|v[1-9][0-9]*)$","default":"DRAFT"}.

DRAFT
sourceRefsTruncated

boolean

Indicates whether the source references are truncated. This parameter is required and always returned. The value is true when a single sourceRefs array contains only the first 1,000 items. You can paginate and verify the remaining items by using the sourceTaskId.

false
sourceTaskId

string

The ID of the source pagination task, which serves as the entry point for the complete sources. This parameter is required and always returned. It must be a non-null locator when sourceRefsTruncated is true. The source operation references held by the artifact or revision remain readable, and archiving the task details does not delete the source manifest. Null values are allowed. The not-equal-to condition can be omitted. Constraints: {"minLength":32,"maxLength":32,"pattern":"^[0-9a-f]{32}$"}.

null
title

string

The display title after authorization. This parameter is required and always returned. Constraints: {"maxLength":1024}.

Warranty instructions
httpStatusCode

integer

The HTTP status code.

0
message

string

The returned message.

success
pageNumber

integer

The page number.

1
pageSize

integer

The number of items per page.

5
queryLabels

array

The query labels.

string

The query labels.

invoice
requestId

string

The request ID.

019FCC42-90DE-56D3-A10D-3C06995DED17
results

array<object>

The list of retrieval results.

array<object>

The retrieval result.

chunkId

string

The chunk ID.

7f0de3e041322a1d
content

string

The chunk content.

Tax amount 1.59
contentType

string

The content type.

table
documentId

string

The document ID.

539ddb688fe811f182f637422a0713b5
documentName

string

The document name.

invoice.pdf
images

array<object>

The list of associated images.

object

The associated image.

imageId

string

The image ID.

kd-620ad908ec651-41253795bafd7a1c
url

string

The temporary access URL.

https://example.com/signed-image
knowledgeBaseId

string

The knowledge base ID.

kd-xxxxxxxxxx
locations

array<object>

The list of document locations.

object

The document location.

bottom

integer

The bottom edge.

364
left

integer

The left edge.

13
pageNumber

integer

The page number.

1
right

integer

The right edge.

566
top

integer

The top edge.

12
mediaEndMs

integer

The end time of the audio or video chunk in the original media, in milliseconds. This parameter is not returned for non-media chunks.

8400
mediaStartMs

integer

The start time of the audio or video chunk in the original media, in milliseconds. This parameter is not returned for non-media chunks.

1250
mediaTimeline

array<object>

The time range of each sentence or paragraph within the chunk in the original media. This parameter is not returned for non-audio chunks.

object

The media timeline segment.

endMs

integer

The end time of the segment.

4200
startMs

integer

The start time of the segment.

1250
text

string

The text of the segment.

The first sentence
parentChunkId

string

The parent chunk ID.

parent-chunk-id
scalarFields

any

The scalar columns of the structured knowledge base. The columns are returned by their original names and are not used for retrieval.

{"question":"How do I reset it?","category":"account"}
score

number

The overall relevance score.

0.26136884
scoreDetails

object

The relevance score details.

keywordScore

number

The keyword relevance score.

0.0000000014285714
semanticScore

number

The semantic relevance score.

0.5227377
tags

array

The list of tags.

string

The tag.

invoice
success

boolean

Indicates whether the request is successful.

true
totalCount

integer

The total number of results.

2

Examples

Success response

JSON format

{
  "accessDeniedDetail": "{\"PolicyType\":\"AccountLevelIdentityBasedPolicy\",\"NoPermissionType\":\"ImplicitDeny\",\"AuthAction\":\"milvusknowledgebase:SearchKnowledgeBase\"}",
  "code": 0,
  "evidenceNextToken": "example-opaque-next-token",
  "evidenceResults": [
    {
      "batchId": "null",
      "chunkId": "null",
      "content": "The warranty period for Product A is 18 months",
      "documentId": "null",
      "entityId": "null",
      "evidenceId": "wiki_section_page_1_sec_1_rev_7",
      "kind": "wiki_section",
      "knowledgeBaseId": "example_kb",
      "pageId": "page_1",
      "relationId": "null",
      "revisionId": "example_value",
      "score": 0.62,
      "sectionId": "sec_1",
      "sourceRefCount": 1,
      "sourceRefs": [
        {
          "chunkId": "example_value",
          "documentId": "example_value",
          "documentName": "example_value",
          "mediaEndMs": 0,
          "mediaStartMs": 0,
          "pageNumber": 1,
          "sourceRevisionId": "example_value",
          "version": "DRAFT"
        }
      ],
      "sourceRefsTruncated": false,
      "sourceTaskId": "null",
      "title": "Warranty instructions"
    }
  ],
  "httpStatusCode": 0,
  "message": "success",
  "pageNumber": 1,
  "pageSize": 5,
  "queryLabels": [
    "invoice"
  ],
  "requestId": "019FCC42-90DE-56D3-A10D-3C06995DED17",
  "results": [
    {
      "chunkId": "7f0de3e041322a1d",
      "content": "Tax amount 1.59",
      "contentType": "table",
      "documentId": "539ddb688fe811f182f637422a0713b5",
      "documentName": "invoice.pdf",
      "images": [
        {
          "imageId": "kd-620ad908ec651-41253795bafd7a1c",
          "url": "https://example.com/signed-image"
        }
      ],
      "knowledgeBaseId": "kd-xxxxxxxxxx",
      "locations": [
        {
          "bottom": 364,
          "left": 13,
          "pageNumber": 1,
          "right": 566,
          "top": 12
        }
      ],
      "mediaEndMs": 8400,
      "mediaStartMs": 1250,
      "mediaTimeline": [
        {
          "endMs": 4200,
          "startMs": 1250,
          "text": "The first sentence"
        }
      ],
      "parentChunkId": "parent-chunk-id",
      "scalarFields": "{\"question\":\"How do I reset it?\",\"category\":\"account\"}",
      "score": 0.26136884,
      "scoreDetails": {
        "keywordScore": 1.4285714e-9,
        "semanticScore": 0.5227377
      },
      "tags": [
        "invoice"
      ]
    }
  ],
  "success": true,
  "totalCount": 2
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.

Previous：GetKnowledgeBasePreSignedUrlNext：Data structure