Updated on 2025-08-13 GMT+08:00

Generating an Answer

Function

This API is used to input content to the model and use the model to generate answers.

Notes:

  1. When chat_id is empty, chat_create_flag is set to 1, indicating that a new chat needs to be started. If chat_id is set, chat_create_flag can be set to 0, indicating that no new chat needs to be started.

  2. The number of elements in messages must be an odd number. For a single-round chat, the number is 1. For a multi-round chat, the number is 3, 5, 7, and so on, for example, [question1, answer1, question2].

  3. In a multi-round chat, the chat sequence is from old to new.

URI

POST /v1/koosearch/experience/chat

Request Parameters

Table 1 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

Parameter description:

Token used for API authentication. For how to obtain the token, see section 3.2 "Authentication."

Constraints:

N/A.

Table 2 Request body parameters

Parameter

Mandatory

Type

Description

repo_id

Yes

String

Parameter description:

Knowledge base ID.

How to obtain:

Log in to the KooSearch experience platform. In the navigation tree on the left, choose Knowledge Bases to view knowledge base IDs. Each knowledge base has a unique ID stored in the vector database.

Constraints:

Not display

extra_repo_ids

No

Array of strings

Parameter description:

List of referenced knowledge base IDs, which is used to support joint retrieval of multiple knowledge bases.

Constraints:

Not limited.

chat_id

No

String

Parameter description:

Current dialogue ID.

** Constraints: **

N/A.

messages

Yes

Array of ChatMessage objects

Dialog content

chat_create_flag

Yes

String

Parameter description:

Whether to start a new round of dialogues (0: no; 1: yes).

1: Clear the historical dialogues and start a new round of dialogues.

0: Continue the chat_id dialog context.

Constraints:

N/A.

refresh_flag

Yes

String

Parameter description:

Indicates whether to clear the Q&A history. The options are as follows: 0: no; 1: yes.

1: Clear the historical conversation.

0: Do not clear the historical conversation.

Constraints:

N/A.

max_tokens

No

Integer

Parameter description:

Maximum number of tokens for text generated by a model.

Constraints:

The total length of the input text plus the generated text cannot exceed the maximum length that the model can process.

Minimum value: 1

stream

No

Boolean

Parameter description:

Whether to use the streaming output mode.

Constraints:

N/A.

filter_string

No

String

Parameter description:

Specifies the filters used during the RAG phase.

A query string with syntax. A parser with strict syntax is used to return documents based on the provided query string.

Example: 'tags:(education OR finance) AND category:"industry knowledge"'

Notes:

  1. Boolean operators AND, OR, and NOT (also written as &&, ||, and !) are supported, but note that they do not follow the usual precedence rules. Parentheses should be used as long as multiple operators are used together.

  2. [For the query string syntax, see the following:] (https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax)

Constraints:

N/A.

top_p

No

Float

Parameter description:

An alternative to temperature sampling, called nucleus sampling, which controls the diversity of generated text by limiting the range of vocabulary choices. A higher top_p value means a wider choice of tokens and hence a higher text diversity.

Constraints:

You are advised to change the value of top_p or temperature to adjust the generating text tendency. Do not change both two parameters.

Options:

0.1 ~ 1

Default value:

0.1

presence_penalty

No

Float

Parameter description:

Degree of duplication in the generated text. The purpose of presence_penalty is to reduce the repeated use of the same or similar content when the model generates text, so as to improve the diversity of the generated text. That is, if a token has appeared in the previous text, the model will be punished when generating this token.

A smaller presence_penalty indicates that the model considers fewer tokens generated previously, which may lead to repeated content in the text.

A larger value of presence_penalty indicates that the model tends to generate new tokens that have not appeared before, and the generated text is more diversified.

Options:

-2 to 2. The specific value needs to be balanced. Generally, the value 1.1 can be used for the Pangu NLP model.

Default value:

0

search_temperature

No

Float

Parameter description:

Diversity and creativity of text generated by the model in search enhancement scenarios.

A value close to 0 indicates the lowest randomness, while 1 indicates the highest randomness. Generally, a lower temperature is suitable for deterministic tasks, higher values favor creative tasks.

Constraints:

N/A.

Options:

0 to 1. For the Pangu NLP model, the value is usually 0.2 or 0.3.

Default value:

0.3

chat_temperature

No

Float

Parameter description:

Diversity and creativity of text generated by the model in non-search enhancement scenarios.

A value close to 0 indicates the lowest randomness, while 1 indicates the highest randomness. Generally, a lower temperature is suitable for deterministic tasks, higher values favor creative tasks.

Constraints:

N/A.

Options:

0 ~ 1.

Table 3 ChatMessage

Parameter

Mandatory

Type

Description

role

No

String

Parameter description:

~~Role in a dialogue. The value can be system or user. ~~

Field to be deleted, which is currently not used.

Constraints:

Field to be deleted, which is currently not used.

content

Yes

String

Parameter description:

User-entered chat content.

Constraints:

N/A.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

chat_id

String

Parameter description:

Current chat ID.

** Constraints: **

N/A.

chat_result

ChatResult object

Dialog result.

references

Array of ChatReferenceInfo objects

Reference result.

reference_total

Integer

Parameter description:

Total number of reference sources.

Constraints:

N/A.

sub_queries

Array of strings

Parameter description:

Query used for search, including the original query and the query rewritten by the search planning module.

Constraints:

N/A.

category

String

Parameter description:

Query type returned by the search planning module.

Constraints:

N/A.

Table 5 ChatResult

Parameter

Type

Description

index

Integer

Parameter description:

Sequence number of a message result.

Constraints:

N/A.

message

String

Parameter description:

Text content of the returned message.

Constraints:

N/A.

question_id

String

Parameter description:

ID of the question corresponding to the returned message.

Constraints:

N/A.

Table 6 ChatReferenceInfo

Parameter

Type

Description

file_id

String

Parameter description:

Document ID (or FAQ ID) of the reference document segment source.

Constraints:

N/A.

title

String

Parameter description:

Title of the document where the referenced segment originates.

Constraints:

N/A.

content

String

Parameter description:

Referenced document segments.

Constraints:

N/A.

big_content

String

Parameter description:

Reference document content context, for example, the original table that is not segmented.

Note:

(1) The search API may have a value.

(2) The Q&A API replaces big_content with content, and this field is cleared.

Constraints:

N/A.

update_date_time

String

Parameter description:

Update time of the reference document segment.

Constraints:

N/A.

doc_type

String

Parameter description:

Type of the referenced segment source (doc: document; faq: FAQ).

Constraints:

N/A.

file_path

String

Parameter description:

Archive path of the reference document shard.

Constraints:

N/A.

category

String

Parameter description:

Document directory, which corresponds to the leaf nodes in the directory tree. This parameter has only one value.

Constraints:

N/A.

tags

Array of strings

Parameter description:

Document tag list.

Constraints:

N/A.

score

Float

Parameter description:

Relevance score of the query and the current reference shard. A higher score indicates a higher relevance.

Constraints:

N/A.

subtitle

String

Parameter description:

Subtitle of the current reference segment in the original text.

Constraints:

N/A.

repo_id

String

Parameter description:

ID of the current knowledge base.

Constraints:

N/A.

chunk_id

String

Parameter description:

ID of the current document chunk.

Constraints:

N/A.

page_num

Integer

Parameter description:

Page number of the current document chunk in the document.

Constraints:

N/A.

component_num

Integer

Parameter description:

Sequence number of the current document segment in the document.

Constraints:

N/A.

Example Requests

The preceding is an example of a multi-round dialog request body.

Note:

When chat_id is empty, chat_create_flag is set to 1, indicating that a new chat needs to be started. If chat_id is set, chat_create_flag can be set to 0, indicating that no new chat needs to be started.

2. The number of elements in messages is always an odd number. In a single round of dialog, the number is 1. In a multi-round dialog, the number is 3, 5, 7, and so on.

As shown in the preceding example, message[0]["content"] is the query of the first round, message[1]["content"] is the answer of the first round, and message[2]["content"] is the query of the second round.

3. The interface supports streaming and non-streaming return, which is controlled by the stream parameter.

POST https://{endpoint}/v1/koosearch/experience/chat

{
  "repo_id" : "acd90739-2e22-4870-b2db-35018699b623",
  "extra_repo_ids" : [ ],
  "chat_id" : "f939c01e-8042-49bb-b207-6575f98bbaeb",
  "messages" : [ {
    "role" : "system",
    "content" : "What are the most common car engine problems?"
  }, {
    "role" : "system",
    "content" : "Car engine problems include the following:\n\n1. Difficulty in starting: The engine cannot start smoothly, which may be caused by insufficient battery power, spark plug problems, or fuel system blockage.\n\n2. Unstable idle: The engine runs unstably at idle, which may cause engine shutdown or severe vibration. This may be caused by problems in the air intake system, fuel system, or ignition system.\n\n3. Reduced power: The engine acceleration performance deteriorates, and the climbing ability decreases, which may be caused by problems in the fuel system, ignition system, or exhaust system.\n\n4. Increased fuel consumption: The fuel consumption of the engine increases abnormally, which may be caused by problems in the fuel system, ignition system, or sensors.\n\n5. Abnormal noise: Abnormal noise occurs during engine operation, which may be caused by mechanical component wear, lubrication system problems, or belt loosening.\n\n6. Overheating: The engine temperature is too high, which may cause the overheating protection switch to start and stop the engine. This may be caused by cooling system faults, water pump faults, or radiator blockage.\n\n7. Oil leakage: Fuel, engine oil, or other liquid leakage occurs inside or outside the engine, which may be caused by aging seals, loose fasteners, or oil circuit blockage.\n\n8. Oil burning: Excessive engine oil consumption may be caused by worn piston rings, damaged valve oil seals, or faults in the crankcase ventilation system.\n\n9. Excessive emissions: Engine exhaust emissions exceeding national standards may be caused by issues in the fuel system, ignition system, or exhaust system.\n\n10. Sensor failure: Faults in some sensors in the engine control system may lead to unstable engine operation, performance degradation, or warning lights.\n\n11. Engine start failure: This may be due to water infiltration into key components such as the distributor, ignition module, spark plugs, or high-voltage wires during engine cleaning; damaged spark plugs can also prevent engine start; insufficient battery power is another significant factor; additionally, the disconnection of the inertia switch may also cause starting difficulties."
  }, {
    "role" : "system",
    "content" : "Anything else?"
  } ],
  "chat_create_flag" : 0,
  "refresh_flag" : 0,
  "stream" : "false",
  "top_p" : 0.1,
  "max_tokens" : 2048,
  "chat_temperature" : 0.8,
  "search_temperature" : 0.3,
  "presence_penalty" : 0
}

Example Responses

Status code: 200

Response body of the model generation result

{
  "chat_id" : "f939c01e-8042-49bb-b207-6575f98bbaeb",
  "category" : "General knowledge",
  "chat_result" : {
    "index" : 0,
    "message" : "Of course, in addition to the engine faults mentioned above, there are some other common problems and phenomena:\n\n11. Fuel injector blockage: The fuel injector is a key component that atomizes and sprays fuel into the combustion chamber. If the fuel injector is blocked, the fuel supply will be insufficient, affecting the engine's power output and fuel consumption.\n\n12. Incorrect ignition timing: Ignition timing refers to the relationship between the ignition moment and the crankshaft position. If the ignition timing is incorrect, the engine's power output will be unstable, fuel consumption will increase, and even knocking will occur.\n\n13. Crankshaft bearing wear: The crankshaft bearing supports the crankshaft and reduces friction. If the crankshaft bearing is severely worn, the engine will vibrate more, fuel consumption will increase, and power will decrease.\n\n14. Piston ring wear: The piston ring seals the combustion chamber and contacts the cylinder wall. If the piston ring is severely worn, air leakage and oil burning will occur.\n\n15. Coolant leakage: Coolant is used to remove the heat generated by the engine. If the coolant leaks, the engine will overheat, and the water temperature gauge will indicate abnormally.\n\n16. Air filter blockage: The air filter is responsible for filtering impurities in the air entering the engine. If the air filter is blocked, it will affect the engine's air intake, leading to reduced power and increased fuel consumption.\n\n17. Spark plug carbon buildup: Carbon buildup on the spark plug can hinder the generation of electric sparks, leading to poor ignition and affecting engine performance.\n\n18. Fuel pump failure: The fuel pump is responsible for delivering fuel from the tank to the engine. If the fuel pump fails, it will result in insufficient fuel supply, affecting engine performance.\n\n19. High-voltage wire aging and breakage: High-voltage wires are responsible for transmitting ignition signals. If they age and break, it will result in poor ignition and affect engine performance.\n\n20. Electronic Control Unit (ECU) failure: The ECU is responsible for receiving signals from various sensors and controlling the engine. If the ECU fails, it will cause unstable engine operation, performance degradation, or warning lights to illuminate.\n\nThese are just some of the engine problems. Specific situations require diagnosis and repair based on actual issues.",
    "question_id" : "312be669-84fc-4d5b-9a66-58a0f3075a5f"
  },
  "sub_queries" : [ "In addition to the engine faults mentioned above, what other faults may occur?", "Anything else?" ],
  "references" : [ {
    "file_id" : "22b179b9de0ad941215cc7f052ab10f8",
    "chunk_id" : "483faffeeb284d20a23378a7d18e9ff1",
    "title" : "What are the problems and symptoms of engine faults?.txt",
    "subtitle" : "Engine problems and phenomena",
    "content" : "1. Difficulty starting: The engine cannot start smoothly, possibly due to insufficient battery power, spark plug issues, or fuel system blockage.\n2. Unstable idle: The engine runs unstably at idle, possibly leading to stalling or severe shaking. This may be due to issues with the air intake system, fuel system, or ignition system.\n3. Reduced power: The engine's acceleration performance decreases, and its hill-climbing ability is reduced, possibly due to issues with the fuel system, ignition system, or exhaust system.\n4. Increased fuel consumption: The engine's fuel consumption abnormally increases, possibly due to issues with the fuel system, ignition system, or sensors.\n5. Abnormal noise: Abnormal noises occur during engine operation, possibly due to mechanical component wear, lubrication system issues, or loose belts.\n6. Overheating: The engine temperature is too high, possibly triggering the overheat protection switch, causing the engine to stop running. This may be due to cooling system failure, water pump failure, or radiator blockage.\n7. Oil leakage: Fuel, oil, or other liquids leak internally or externally from the engine, possibly due to aging seals, loose fasteners, or oil circuit blockage.\n8. Oil burning: Excessive engine oil consumption, possibly due to worn piston rings, damaged valve oil seals, or crankcase ventilation system failure.\n9. Excessive emissions: Engine exhaust emissions exceed national standards, possibly due to issues with the fuel system, ignition system, or exhaust system.",
    "file_path" : "uni-search/files/b25446daeb1a41a7953c5deba2b2677a/fb9731ab-7085-474f-b6c7-64473586f0f3/acd90739-2e22-4870-b2db-35018699b623/22b179b9de0ad941215cc7f052ab10f8/ Engine problems and phenomena.txt",
    "category" : "",
    "update_date_time" : "1731049431328",
    "repo_id" : "acd90739-2e22-4870-b2db-35018699b623",
    "page_num" : 1,
    "component_num" : 1,
    "score" : 0.9049869
  }, {
    "file_id" : "22b179b9de0ad941215cc7f052ab10f8",
    "chunk_id" : "389497084e3f44e589b635f9a1ef4f2f",
    "title" : "What are the problems and symptoms of engine faults?.txt",
    "subtitle" : "What are the problems and symptoms of engine faults?",
    "content" : "10. Sensor fault: Some sensors in the engine control system may be faulty, which may cause the engine to run unstably, performance to deteriorate, or the warning light to turn on.",
    "file_path" : "uni-search/files/b25446daeb1a41a7953c5deba2b2677a/fb9731ab-7085-474f-b6c7-64473586f0f3/acd90739-2e22-4870-b2db-35018699b623/22b179b9de0ad941215cc7f052ab10f8/ What are the problems and symptoms of engine faults?.txt",
    "category" : "",
    "update_date_time" : "1731049431328",
    "repo_id" : "acd90739-2e22-4870-b2db-35018699b623",
    "page_num" : 1,
    "component_num" : 2,
    "score" : 0.79597545
  }, {
    "file_id" : "b7947c56436d29bf7671844d7f57371e",
    "chunk_id" : "0512b8fe109941208de99b4470ab2de3",
    "title" : "Engine abnormal.txt",
    "subtitle" : "Engine abnormal\n1. Engine startup failure:",
    "content" : "This may be because water has seeped into key components such as the distributor, ignition module, spark plug, or high-voltage wire during engine cleaning.\nA damaged spark plug may also prevent the engine from starting.\nLow battery power is also an important reason.\nIn addition, the disconnection of the inertia switch may also cause starting problems.",
    "file_path" : "uni-search/files/b25446daeb1a41a7953c5deba2b2677a/fb9731ab-7085-474f-b6c7-64473586f0f3/acd90739-2e22-4870-b2db-35018699b623/b7947c56436d29bf7671844d7f57371e/ Engine abnormal.txt",
    "category" : "",
    "update_date_time" : "1731049431522",
    "repo_id" : "acd90739-2e22-4870-b2db-35018699b623",
    "page_num" : 1,
    "component_num" : 2,
    "score" : 0.29695997
  } ],
  "rac" : null,
  "reference_total" : 3
}

Status Codes

Status Code

Description

200

Response body of the model generation result

Error Codes

See Error Codes.