Use SearchKnowledge for text-based question answering - OpenSearch

Text Q&A answers queries by retrieving content from a knowledge base. It uses a session ID to maintain context in multi-turn conversations. You can also select different Large Language Models (LLMs) to generate answers and customize the responses.

Prerequisites

Obtain an API key to authenticate calls to OpenSearch - LLM Intelligent Q&A Edition. For more information, see Manage API keys.
Obtain a service endpoint to make calls to OpenSearch - LLM Intelligent Q&A Edition. For more information, see Obtain service endpoints.

Important

This API is designed for server-side use and must not be called directly from a front-end environment such as a browser, mini program, or mobile app. There are two reasons for this. First, the API uses the Authorization: Bearer <API key> header for authentication. An API key is a long-term credential; embedding it in front-end code would expose it to theft. Second, the API does not support Cross-Origin Resource Sharing (CORS), so browsers will block any direct calls. You must store the API key on your server, make calls from the server, and then return the results to the front end.

API

Request method	Protocol	Request format
POST	HTTP	JSON

Request URL

{host}/v3/openapi/apps/{app_group_identity}/actions/knowledge-search

{host}: The service endpoint, accessible over the Internet or a virtual private cloud (VPC). For more information, see Obtain endpoints.
{app_group_identity}: The application name. Sign in to the OpenSearch LLM-Based Conversational Search Edition console and find this name on the Instance Management page.

Request parameters

Header parameters

Parameter	Type	Required	Description	Example
Content-Type	string	Yes	Specifies the media type of the request body. Must be "application/json".	application/json
Authorization	string	Yes	Your API key, prefixed with "Bearer ".	Bearer OS-d1**2a
accept	string	No	Set to "text/event-stream" to receive streaming responses using Server-Sent Events (SSE).	text/event-stream

Body parameters

Parameter	Type	Required	Description	Example value
question	map	Yes	The input question.	{ "text":"user question", "type": "TEXT", "session" : "" }
question.text	string	Yes	The text content of the user's question.	user question
question.session	string	No	A session ID that identifies the context of a multi-turn conversation. Valid values: If this parameter is not set or is left empty, multi-turn conversation is disabled. If you provide a non-empty value, multi-turn conversation is enabled. The system retains conversations with the same session ID for context. The system retains conversation history for up to 7 days. Use the `history_max` parameter to specify the number of conversation turns to retain (up to 20).	1725530408586
question.type	string	No	The type of the input question. Set this to `TEXT`.	TEXT
options	map	No	Optional parameters to control settings such as retrieval, model selection, and prompts.
options.chat	map	No	Parameters for accessing a Large Language Model (LLM).
options.chat.disable	boolean	No	Specifies whether to disable access to the LLM. `false`: Accesses the LLM to summarize and generate the result. This is the default value. `true`: Does not access the LLM.	false
options.chat.stream	boolean	No	Specifies whether to enable a streaming response. `true`: Enables a streaming response. This is the default value. `false`: Disables the streaming response.	true
options.chat.model	string	No	The Large Language Model (LLM) to use. Valid values: Asia Pacific SE 1 (Singapore) opensearch-llama2-13b opensearch-falcon-7b qwen-turbo qwen-plus qwen-max qwen2-72b-instruct	opensearch-llama2-13b
options.chat.enable_deep_search	boolean	No	Specifies whether to enable deep search. `true`: Enables deep search. This feature uses multi-turn reasoning to synthesize data for the final response, which can increase the time and computing resources used per conversation turn. `false`: Disables deep search.	false
options.chat.model_generation	integer	No	Specifies the model version to use for a custom product model. If you do not specify this parameter, the system uses the oldest version by default.	20
options.chat.prompt_template	string	No	The name of a custom prompt template. If this parameter is empty, the system uses its built-in prompt template by default.	user_defined_prompt_name
options.chat.prompt_config	object	No	The key-value pairs for configuring a custom prompt. The parameter must be in the following format: `{ "String_key": "value", "Integer_key" : 1 }`	`{ "attitude": "normal", "rule" : "detailed", "noanswer": "sorry", "language": "Chinese", "role": false, "role_name": "AI Assistant", }`
options.chat.prompt_config.attitude	string	No	A parameter for the built-in prompt template that controls the tone of the response. The default value is `normal`. `normal`: A neutral tone. `polite`: A friendly and courteous tone. `patience`: A tactful and patient tone.	normal
options.chat.prompt_config.rule	string	No	Controls the level of detail in the response. The default value is `detailed`. `detailed`: Detailed and professional. `stepbystep`: Detailed and step-by-step.	detailed
options.chat.prompt_config.noanswer	string	No	The response to return when the system cannot answer the question. The default value is `sorry`. `sorry`: "Sorry, I cannot answer this question based on the available information." `uncertain`: "I don't know."	sorry
options.chat.prompt_config.language	string	No	The language to use for the response. The default value is `Chinese`. `Chinese`: Chinese. `English`: English. `Thai`: Thai. `Korean`: Korean.	Chinese
options.chat.prompt_config.role	boolean	No	Specifies whether to enable a custom persona for the response. If you set this to `true`, the system generates responses based on the persona defined in `role_name`.	false
options.chat.prompt_config.role_name	string	No	The name of the custom persona. For example: AI Assistant.	AI Assistant
options.chat.prompt_config.out_format	string	No	The format of the output content. The default value is `text`. `text`: Text. `table`: Table. `list`: List. `markdown`: Markdown.	text
options.chat.generate_config.repetition_penalty	float	No	Controls the penalty for repetition in generated token sequences. A higher value reduces the likelihood of repetition. A value of `1.0` indicates no penalty. There is no strict value range.	1.01
options.chat.generate_config.top_k	integer	No	The number of highest-probability tokens to consider for sampling. For example, a value of `50` instructs the model to sample from only the 50 tokens with the highest scores. A higher value increases randomness, while a lower value increases determinism. The default value is `0`, which disables the top-k strategy and relies on the top-p strategy instead.	50
options.chat.generate_config.top_p	float	No	The cumulative probability threshold for nucleus sampling. For example, a value of `0.8` means the model selects from the smallest possible set of tokens whose cumulative probability is at least 0.8. Valid values are in the range (0, 1.0). A higher value increases randomness, while a lower value increases determinism.	0.5
options.chat.generate_config.temperature	float	No	Controls the randomness and diversity of generated text. A higher temperature flattens the probability distribution of candidate tokens, allowing the model to choose less likely tokens and making the output more diverse. A lower value sharpens the distribution, making the model more likely to select high-probability tokens and the output more deterministic. Value range: [0, 2). Do not set this parameter to 0. python version >=1.10.1 java version >= 2.5.1	0.7
options.chat.history_max	integer	No	The maximum number of turns to retain in the history of a multi-turn conversation. The maximum value is 20. The default value is 1.	20
options.chat.link	boolean	No	Specifies whether to include source citations in the response. Valid values: `true`: The response includes source citations. `false`: The response does not include source citations. This is the default value. The following is an example of a response that contains citations: You can expand the capacity of an ECS disk either online or offline[^1^]. Online expansion does not require you to restart the instance, while offline expansion does[^1^]. To perform the expansion, go to the ECS console, select the disk, and choose Expand Disk from the Actions column. Then, select an expansion method as needed[^1^]. If you need to expand partitions and file systems, you can do so from the console[^2^]. After the disk capacity is expanded, it cannot be reduced, so plan your storage space accordingly[^3^]. The numbers enclosed in `[^` and `^]` correspond to the documents in the `reference` object of the API response. For example, `[^1^]` refers to the first document in the `reference` object.	false
options.chat.rich_text_strategy	string	No	The post-processing strategy for output from a rich-text LLM. If this parameter is empty or not specified, rich text processing is disabled by default. `inside_response`: Renders rich text tags directly within the response content in Markdown format. Tables are inserted as HTML within the Markdown. `extend_response`: If the response contains rich text tags, the content for each tag is returned separately in the rich_text_ref object. For example, image content is returned as a URL, table content as HTML, and code content as plain text.	inside_response
options.chat.agent	map	No	Specifies options for the RAG agent's tool-use capabilities. When enabled, the model decides whether to execute a tool based on the available content. The LLMs that currently support this feature are: qwen-plus qwen-max qwen2-72b-instruct
options.chat.agent.think_process	boolean	No	Specifies whether to return the agent's thought process.	true
options.chat.agent.max_think_round	integer	No	The maximum number of thought rounds for the agent. The value cannot exceed 20.	10
options.chat.agent.language	string	No	The language for the thought process and the final answer. `AUTO`: Automatically determines whether to use Chinese or English based on the user query. `CN`: Chinese. `EN`: English.	AUTO
options.chat.agent.tools	list of string	No	The RAG tools that the agent can use. The following tools are available: `knowledge_search`: Performs retrieval from the knowledge base.	["knowledge_search"]
options.retrieve	map	No	Specifies parameters that control the retrieval process.
options.retrieve.web_search.enable	boolean	No	Specifies whether to enable web search. `true`: Enables web search. The system generates the response based on data from the web search, which can increase time and resource consumption. `false`: Disables web search. This is the default value.	false
doc	map	No	Specifies parameters related to document retrieval.
options.retrieve.doc.disable	boolean	No	Specifies whether to disable retrieval from the knowledge base. `false`: Enables retrieval. This is the default value. `true`: Disables retrieval.	false
options.retrieve.doc.filter	string	No	A filter expression to select data for retrieval from the knowledge base. If not specified, no filter is applied. For syntax examples, see filter parameter. Supported fields: `table`: The table where the document is stored. `raw_pk`: The primary key of the document. `category`: The category of the document. `score`: The score of the document. `timestamp`: The timestamp of the document. Example format: "filter" : "raw_pk=\"123\"" # Retrieves data only from the document with the ID 123. "filter" : "category=\"value1\"" # Retrieves data only from documents in the "value1" category. "filter" : "category=\"value1\" OR category=\"value2\"" # Retrieves data from documents in the "value1" and "value2" categories. "filter" : "score>1.0" # Retrieves data only from documents with a score greater than 1.0. "filter" : "timestamp>1356969600" # Retrieves data only from documents with a timestamp after 2013-01-01.	category=\"value1\"
options.retrieve.doc.sf	float	No	The score threshold for vector-based retrieval. When sparse vectors are disabled: The value range is `[0, 2.0]`, and the default value is `1.3`. A lower value yields more relevant but fewer results. A higher value may retrieve less relevant results. When sparse vectors are enabled: The default value is `0.35`. A higher value yields more relevant but fewer results. A lower value may retrieve less relevant results.	0.35
options.retrieve.doc.top_n	integer	No	The number of documents to retrieve. The value must be in the range (0, 50]. The default value is 5.	5
options.retrieve.doc.formula	string	No	A custom ranking formula for retrieved documents. Note For syntax details, refer to Business Sorting Functions. The Algorithmic Relevance and Geographic Relevance features are not supported.	-timestamp: Sorts documents in descending order by the timestamp field.
options.retrieve.doc.rerank_size	integer	No	The number of documents to rerank when the rerank feature is enabled. The value must be in the range (0, 100]. The default value is 30.	30
options.retrieve.doc.operator	string	No	The relationship between the terms that result from tokenizing `question.text` for knowledge base retrieval. This parameter is effective only when you disable sparse vectors. `AND`: All terms must appear in a document for it to be retrieved. This is the default value. `OR`: At least one term must appear in a document for it to be retrieved.	AND
options.retrieve.doc.dense_weight	float	No	When sparse vectors are enabled, this parameter controls the weight of the dense vector during document retrieval. The value must be in the range (0.0, 1.0). The default value is 0.7.	0.7
options.retrieve.entry	map	No	Specifies parameters for retrieving results from manual intervention data.
options.retrieve.entry.disable	boolean	No	Specifies whether to disable retrieval from manual intervention data. `false`: Enables retrieval. This is the default value. `true`: Disables retrieval.	false
options.retrieve.entry.sf	float	No	The vector score threshold for retrieving manual intervention data. The value range is `[0, 2.0]`, and the default value is `0.3`. A lower value retrieves fewer but more relevant results, while a higher value may retrieve less relevant results.	0.3
options.retrieve.image	map	No	Specifies parameters for retrieving image results from the knowledge base.
options.retrieve.image.disable	boolean	No	Specifies whether to disable image retrieval. The default value is `false`. `false`: Enables image retrieval. This is the default value. `true`: Disables image retrieval.	false
options.retrieve.image.sf	float	No	The score threshold for image vector retrieval. When sparse vectors are disabled: The value range is `[0, 2.0]`, and the default value is `1.0`. A lower value yields more relevant but fewer results. A higher value may retrieve less relevant results. When sparse vectors are enabled: The default value is `0.5`. A higher value yields more relevant but fewer results. A lower value may retrieve less relevant results.	1.0
options.retrieve.image.dense_weight	float	No	When sparse vectors are enabled, this parameter controls the weight of the dense vector during image retrieval. The value must be in the range (0.0, 1.0). The default value is 0.7.	0.7
options.retrieve.qp	map	No	Specifies options for query rewriting.
options.retrieve.qp.query_extend	boolean	No	Specifies whether to expand the user query. The search engine uses the expanded query to retrieve document chunks. `false`: Does not expand the query. This is the default value. `true`: Expands the query. This option requires an additional call to the LLM, which increases response latency. Do not enable this for latency-sensitive applications.	false
options.retrieve.qp.query_extend_num	integer	No	When query expansion is enabled, this parameter specifies the maximum number of additional queries to generate. The default value is 5.	5
options.retrieve.rerank	map	No	Specifies options for reranking retrieved documents.
options.retrieve.rerank.enable	boolean	No	Specifies whether to use a model to rerank search results for relevance. Valid values: `true`: Reranks the results by using a model. `false`: Does not rerank the results. The default is `false` if `options.retrieve.doc.formula` is specified; otherwise, it is `true`.	true
options.retrieve.rerank.model	string	No	The name of the large model to use for reranking. `ops-bge-reranker-larger`: The bge-reranker model. This is the default. `ops-text-reranker-001`: A proprietary reranker model.	ops-bge-reranker-larger
options.retrieve.return_hits	boolean	No	Specifies whether to return the document retrieval results, which correspond to the `search_hits` object in the response.	false

Request body

{
  "question": {
    "text": "What is Alibaba Cloud OpenSearch?",
    "session": "session_001",
    "type": "TEXT"
  },
  "options": {
    "chat": {
      "disable": false,
      "stream": false,
      "model": "Qwen",
      "history_max": 20,
      "link": false,
      "agent": {
        "tools": ["knowledge_search"]
      }
    },
    "retrieve": {
      "doc": {
        "disable": false,
        "filter": "category=\"type\"",
        "sf": 0.35,
        "top_n": 5,
        "operator": "OR"
      },
      "web_search": { "enable": false },
      "entry": { "disable": false, "sf": 0.3 },
      "image": { "disable": false, "sf": 1.0 },
      "rerank": {
        "enable": true,
        "model": "ops-bge-reranker-larger"
      },
      "return_hits": false
    }
  }
}

Key parameters:

Use question.session to enable multi-turn conversation context.
Set options.chat.disable to true to skip the LLM and return retrieval results.
Use options.retrieve.doc.top_n to specify the number of retrieved documents. The default is 5.
Set options.retrieve.return_hits to true to return the detailed content of search_hits.

Response parameters

Parameter	Type	Description
request_id	string	Unique request identifier. Include this value in support requests.
status	string	The processing status of the request. `OK`: The request succeeded. `FAIL`: The request failed.
latency	float	Server processing time in milliseconds. Returned only when the request succeeds.
id	integer	The primary key.
title	string	Document title.
category	string	Category name.
url	string	Document URL.
answer	string	The generated answer.
type	string	Result type.
scores	array	Document relevance scores.
event	string	The type of streaming event. A thinking round includes `THINK`, `ACTION`, and `ANSWER` events, although `THINK` is optional. These events indicate the model's thinking process (`THINK`), the action performed (`ACTION`), and the conclusion of the current round (`ANSWER`). `SUMMARY` provides the final answer and is returned only once.
event_status	string	Indicates whether the event is complete. `PROCESSING`: The event is in progress. `FINISHED`: The event is complete.
code	string	The error code. Returned only when an error occurs.
message	string	The error message. Returned only when an error occurs.

Sample response body

Successful response

{
  "request_id": "6859E98D-D885-4AEF-B61C-9683A0184744",
  "status": "OK",
  "latency": 6684.41,
  "result": {
    "data": [
      {
        "answer": "Alibaba Cloud OpenSearch is a managed service for searching structured data...",
        "type": "TEXT",
        "reference": [
          {"url": "https://www.alibabacloud.com/help/document_detail/463469.html", "title": "OpenSearch Product Introduction"}
        ]
      }
    ],
    "search_hits": [
      {
        "fields": {"content": "Content of OpenSearch-related documents...", "title": "OpenSearch Introduction"},
        "scores": ["0.9778"],
        "type": "DOC"
      }
    ]
  }
}

Error response

{
  "request_id": "e579a090bf99dc787d29d878b40c8367",
  "status": "FAIL",
  "errors": [
    {"code": 3005, "message": "topN[51] is not in (0, 50]"}
  ]
}