This topic describes how to use an API to call a legacy Alibaba Cloud Model Studio retrieval-augmented generation (RAG) application.
On May 3, 2024, Alibaba Cloud Model Studio was upgraded. For more information about the upgrade, see Official pre-built application upgrade announcement. After this upgrade, you can no longer create legacy RAG applications. If your application was created before this upgrade, you can continue to use this topic to call your application.
-
To learn how to migrate your enterprise knowledge base to the new knowledge base and build a new RAG application, see Migration plan below.
-
To learn how to call a new RAG application from your business code using an HTTP interface or a software development kit (SDK), see Call an application.
Migration plan
The enterprise knowledge base feature is no longer maintained. We recommend that you migrate your private knowledge to the new knowledge base as soon as possible. Alibaba Cloud does not currently provide official migration tools or services. The new knowledge base offers more features and supports more document formats.
|
Enterprise knowledge type |
Migration plan |
|
Documents |
Create an unstructured knowledge base to manage document-based knowledge. Import documents by uploading them from your local machine or from Object Storage Service (OSS). If you upload from a local machine, you must manually update the knowledge base later. If you import from OSS, you can integrate OSS, Function Compute (FC), and the Alibaba Cloud Model Studio knowledge base API to enable automatic data updates. You can upload local files using the console or an API. You can only import from OSS using the console. For more information, see Knowledge base: Step 1. Import data. |
|
FAQ |
Create a structured knowledge base to manage FAQ-style knowledge. You can create a structured knowledge base by uploading local documents or using ApsaraDB RDS. If you upload local documents, you must manually update the knowledge base later. If you use ApsaraDB RDS, data updates in the RDS table are automatically synchronized to the knowledge base. Currently, both methods can only be performed in the console. For more information, see Knowledge base: Step 1. Import data. |
After you create a new knowledge base, you can associate it with your Agent Application or Workflow Application in My Applications. For more information, see Knowledge base: Step 4. Reference the knowledge base.
Use the SDK
Prerequisites
-
You have obtained an API key and configured it as an environment variable. For more information, see Obtain an API key and Configure an API key.
-
The DashScope SDK is installed. Python and Java versions are available. For more information, see Install the latest version of the SDK.
-
A RAG application is created and enterprise knowledge is uploaded. You can no longer create new legacy RAG applications. For more information, see Upload enterprise knowledge.
-
Obtain the APP_ID. You can view it on the application card on the My Applications page.
Call examples
from http import HTTPStatus
from dashscope import Application
def rag_call():
response = Application.call(app_id='YOUR_APP_ID',
prompt='How is the TopP parameter passed in the API operation description?',
)
if response.status_code != HTTPStatus.OK:
print('request_id=%s, code=%s, message=%s\n' % (response.request_id, response.status_code, response.message))
else:
print('request_id=%s\n output=%s\n usage=%s\n' % (response.request_id, response.output, response.usage))
if __name__ == '__main__':
rag_call()
import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import java.util.List;
public class Main{
public static void ragCall()
throws ApiException, NoApiKeyException, InputRequiredException {
RagApplicationParam param = RagApplicationParam.builder()
.appId("YOUR_APP_ID")
.prompt("How is the TopP parameter passed in the API operation description?")
.build();
Application application = new Application();
ApplicationResult result = application.call(param);
System.out.printf("requestId: %s, text: %s, finishReason: %s\n",
result.getRequestId(), result.getOutput().getText(), result.getOutput().getFinishReason());
if (result.getUsage() != null && result.getUsage().getModels() != null) {
for (ApplicationUsage.ModelUsage usage : result.getUsage().getModels()) {
System.out.printf("modelId: %s, inputTokens: %d, outputTokens: %d\n",
usage.getModelId(), usage.getInputTokens(), usage.getOutputTokens());
}
}
}
public static void main(String[] args) {
try {
ragCall();
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
throw new RuntimeException(e);
}
System.exit(0);
}
}Retrieve by tag
If your enterprise knowledge base contains a large volume of data, use tag-based retrieval to improve recall accuracy.
First, add knowledge tags to your documents. For more information, see Upload enterprise knowledge.
Then, obtain the tag IDs and pass them in the `doc_tag_codes` parameter. You can pass multiple tag IDs.
When you pass tags, the retrieval process is limited to the documents associated with those tags, not the entire knowledge base.
from http import HTTPStatus
from dashscope import Application
def rag_call_with_tags():
response = Application.call(app_id='YOUR_APP_ID',
prompt='How is the TopP parameter passed in the API operation description?',
doc_tag_codes=['471d*******3427', '471d*******3428'], # Specify a tag scope for retrieval.
doc_reference_type=Application.DocReferenceType.simple, # The result does not include reference markers.
has_thoughts=True # Enable the return of retrieval process information.
)
if response.status_code != HTTPStatus.OK:
print('request_id=%s, code=%s, message=%s\n' % (response.request_id, response.status_code, response.message))
else:
print('request_id=%s\n output=%s\n usage=%s\n' % (response.request_id, response.output, response.usage))
thoughts = response.output.thoughts
if thoughts is not None:
for thought in thoughts:
print('thought=%s' % thought)
if __name__ == '__main__':
rag_call_with_tags()
import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import java.util.List;
import java.util.Arrays;
public class Main {
public static void ragCallWithTags()
throws ApiException, NoApiKeyException, InputRequiredException {
RagApplicationParam param = RagApplicationParam.builder()
.appId("YOUR_APP_ID")
.prompt("How is the TopP parameter passed in the API operation description?")
// Specify a tag scope for retrieval.
.docTagCodes(Arrays.asList("471d*******3427", "471d*******3428"))
// The result does not include reference markers.
.docReferenceType(RagApplicationParam.DocReferenceType.SIMPLE)
// Enable the return of retrieval process information.
.hasThoughts(true)
.build();
Application application = new Application();
ApplicationResult result = application.call(param);
System.out.printf("requestId: %s, text: %s, finishReason: %s\n",
result.getRequestId(), result.getOutput().getText(), result.getOutput().getFinishReason());
List<ApplicationOutput.Thought> thoughts = result.getOutput().getThoughts();
if (thoughts != null && thoughts.size() > 0) {
for (ApplicationOutput.Thought thought : thoughts) {
System.out.printf("thought: %s\n", thought);
}
}
}
public static void main(String[] args) {
try {
ragCallWithTags();
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
System.out.printf("Exception: %s", e.getMessage());
}
System.exit(0);
}
}
Multi-turn conversation
Cloud-hosted multi-turn conversation
Alibaba Cloud Model Studio applications provide a cloud-hosted multi-turn conversation feature. Use the `session_id` to conduct multi-turn conversations. Alibaba Cloud automatically manages the conversation history, so you do not need to maintain it on the client side.
In the following example, the first call returns a `session_id`. When you pass this `session_id` in the second call, the model service includes the session information from the first call.
The session ID is valid for one hour. The maximum number of conversation turns in the history is 50.
If you pass both `session_id` and `history`, the `history` parameter takes precedence, and the cloud-hosted conversation is not used.
from http import HTTPStatus
from dashscope import Application
def call_with_session():
response = Application.call(app_id='YOUR_APP_ID',
prompt='I want to go to Xinjiang',
)
if response.status_code != HTTPStatus.OK:
print('request_id=%s, code=%s, message=%s\n' % (response.request_id, response.status_code, response.message))
return
response = Application.call(app_id='your app id',
prompt='What tourist attractions or food are there?',
session_id=response.output.session_id
)
if response.status_code != HTTPStatus.OK:
print('request_id=%s, code=%s, message=%s\n' % (response.request_id, response.status_code, response.message))
else:
print('request_id=%s, output=%s, usage=%s\n' % (response.request_id, response.output, response.usage))
if __name__ == '__main__':
call_with_session()
import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import java.util.Arrays;
import java.util.List;
public class Main {
public static void callWithSession()
throws ApiException, NoApiKeyException, InputRequiredException {
ApplicationParam param = ApplicationParam.builder()
.appId("YOUR_APP_ID")
.prompt("I want to go to Xinjiang")
.build();
Application application = new Application();
ApplicationResult result = application.call(param);
param.setSessionId(result.getOutput().getSessionId());
param.setPrompt("What tourist attractions or food are there?");
result = application.call(param);
System.out.printf("requestId: %s, text: %s, finishReason: %s\n",
result.getRequestId(), result.getOutput().getText(), result.getOutput().getFinishReason());
}
public static void main(String[] args) {
try {
callWithSession();
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
System.out.printf("Exception: %s", e.getMessage());
}
System.exit(0);
}
}Client-side multi-turn conversation
If you maintain the conversation history on the client side, you can pass the conversation information in the `history` parameter.
from http import HTTPStatus
from dashscope import Application
def call_with_history():
prompt = 'I want to go to Xinjiang'
response = Application.call(app_id="YOUR_APP_ID",
prompt=prompt,
)
if response.status_code != HTTPStatus.OK:
print('request_id=%s, code=%s, message=%s\n' % (response.request_id, response.status_code, response.message))
return
history = [{'user': prompt, 'bot': response.output.text}]
response = Application.call(app_id="YOUR_APP_ID",
prompt='What tourist attractions or food are there?',
history=history
)
if response.status_code != HTTPStatus.OK:
print('request_id=%s, code=%s, message=%s\n' % (response.request_id, response.status_code, response.message))
else:
print('request_id=%s, output=%s, usage=%s\n' % (response.request_id, response.output, response.usage))
if __name__ == '__main__':
call_with_history()
import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.common.History;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import java.util.Arrays;
import java.util.List;
public class Main {
public static void callWithHistory()
throws ApiException, NoApiKeyException, InputRequiredException {
String prompt = "I want to go to Xinjiang";
ApplicationParam param = ApplicationParam.builder()
.appId(APP_ID)
.prompt("I want to go to Xinjiang")
.build();
Application application = new Application();
ApplicationResult result = application.call(param);
param.setHistory(Arrays.asList(History.builder()
.user(prompt)
.bot(result.getOutput().getText())
.build()));
param.setPrompt("What tourist attractions or food are there?");
result = application.call(param);
System.out.printf("requestId: %s, text: %s, finishReason: %s\n",
result.getRequestId(), result.getOutput().getText(), result.getOutput().getFinishReason());
}
public static void main(String[] args) {
try {
callWithHistory();
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
System.out.printf("Exception: %s", e.getMessage());
}
System.exit(0);
}
}Streaming output
To enable streaming output, add the corresponding parameter. In the Python SDK, add `stream=True`. In the Java SDK, use the `streamCall` interface.
from http import HTTPStatus
from dashscope import Application
def call_with_stream():
responses = Application.call(app_id='YOUR_APP_ID',
prompt='How to make scrambled eggs with tomatoes?',
stream=True
)
for response in responses:
if response.status_code != HTTPStatus.OK:
print('request_id=%s, code=%s, message=%s\n' % (
response.request_id, response.status_code, response.message))
else:
print('output=%s, usage=%s\n' % (response.output, response.usage))
if __name__ == '__main__':
call_with_stream()
import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import io.reactivex.Flowable;
import java.util.Arrays;
import java.util.List;
public class Main {
public static void streamCall() throws NoApiKeyException, InputRequiredException {
ApplicationParam param = ApplicationParam.builder()
.appId("YOUR_APP_ID")
.prompt("How to cook braised pig's feet with potatoes?")
.build();
Application application = new Application();
Flowable<ApplicationResult> result = application.streamCall(param);
result.blockingForEach(data -> {
System.out.printf("requestId: %s, text: %s, finishReason: %s\n",
data.getRequestId(), data.getOutput().getText(), data.getOutput().getFinishReason());
});
}
public static void main(String[] args) {
try {
streamCall();
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
System.out.printf("Exception: %s", e.getMessage());
}
System.exit(0);
}
}Workspaces
The preceding examples call an application in the default workspace. To call an application in a different workspace, you must pass the specific workspace ID.
Replace `YOUR_WORKSPACE` in the example with your actual workspace ID to ensure the code runs correctly. To obtain the workspace ID, see Obtain a workspace ID.
from http import HTTPStatus
from dashscope import Application
def call_with_workspace():
response = Application.call(app_id='YOUR_APP_ID',
workspace='YOUR_WORKSPACE',
prompt='How to make scrambled eggs with tomatoes?',
)
if response.status_code != HTTPStatus.OK:
print('request_id=%s, code=%s, message=%s\n' % (response.request_id, response.status_code, response.message))
else:
print('request_id=%s, text=%s, usage=%s\n' % (response.request_id, response.output.text, response.usage))
if __name__ == '__main__':
call_with_workspace()
import com.alibaba.dashscope.app.*;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
public class Main {
public static void callWithWorkspace() throws NoApiKeyException, InputRequiredException {
ApplicationParam param = ApplicationParam.builder()
.workspace("YOUR_WORKSPACE")
.appId("YOUR_APP_ID")
.prompt("How to cook braised pig's feet with potatoes?")
.build();
Application application = new Application();
ApplicationResult result = application.call(param);
System.out.printf("requestId: %s, text: %s, finishReason: %s\n",
result.getRequestId(), result.getOutput().getText(), result.getOutput().getFinishReason());
}
public static void main(String[] args) {
try {
callWithWorkspace();
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
System.out.printf("Exception: %s", e.getMessage());
}
System.exit(0);
}
}Input parameters
|
Parameter |
Type |
Default |
Description |
|
app_id |
string |
- |
The application ID. |
|
prompt |
string |
- |
The instruction that you want the model to execute. This guides the model in generating a response. |
|
session_id |
string |
- |
The unique ID of a conversation session. If you pass a session_id, the conversation history is recorded in the cloud. The LLM automatically includes the stored conversation history in subsequent calls. Make sure that the session_id is unique. You can use either session_id or history, but not both. |
|
history (optional) |
list[dict] |
[] |
The conversation history between the user and the model. Each element in the list is a turn in the conversation, formatted as {"user": "user input", "bot": "model output"}. The turns are arranged chronologically. |
|
workspace (optional) |
string |
- |
The workspace ID. |
|
seed (optional) |
int |
1234 |
The random number seed used for generation. This controls the randomness of the model's output. The seed must be an unsigned 64-bit integer. The default value is 1234. When a seed is used, the model tries to produce the same or similar results, but identical results are not guaranteed for every generation. |
|
top_p (optional) |
float |
0.2 |
The probability threshold for nucleus sampling. For example, a value of 0.2 means that only the smallest set of most-likely tokens with a cumulative probability of 0.2 or higher are kept as the candidate set. The value must be in the range of (0, 1.0). A higher value increases randomness, while a lower value increases determinism. |
|
top_k (optional) |
int |
None |
The size of the candidate set for sampling. For example, a value of 50 means that only the 50 tokens with the highest scores are included in the candidate set for random sampling. A higher value increases randomness, while a lower value increases determinism. If this parameter is not passed, is set to None, or is greater than 100, the top_k policy is not used, and only the top_p policy is in effect. |
|
temperature (optional) |
float |
1.0 |
Controls the degree of randomness and diversity. The temperature value smooths the probability distribution of candidate words. A higher temperature value flattens the distribution, allowing less probable words to be selected and making the output more diverse. A lower temperature value sharpens the distribution, making more probable words more likely to be selected and making the output more deterministic. Valid values: [0, 2). A value of 0 is not recommended because it is meaningless. python version >=1.10.1 java version >= 2.5.1 |
|
stream (optional) |
bool |
False |
Specifies whether to use streaming output. When streaming is enabled, the API operation returns a generator. You must iterate through the generator to get the results. By default, each output is the entire sequence generated so far, and the final output is the complete result. You can set the incremental_output parameter to False to change to non-incremental output mode. |
|
doc_tag_codes (optional) |
list[str] |
- |
A list of document tag codes. When you pass a list of tag codes, the retrieval process is limited to the documents associated with those tags. |
|
doc_reference_type |
str |
- |
The reference data type for the retrieved documents. Set the value to `simple`. If you set the value to `simple`, the response does not contain reference markers. |
|
has_thoughts |
bool |
False |
Specifies whether to output information about the retrieval and recall process. If enabled, the response includes details about the document retrieval, recall, and model inference processes. |
Output parameters
|
Response parameter |
Type |
Description |
Remarks |
|
status_code |
int |
A value of 200 (HTTPStatus.OK) indicates that the request was successful. Otherwise, the request failed. You can get the error code from the `code` field and the detailed error message from the `message` field. Note This field is for Python only. In Java, a failure throws an exception that contains the code and message. |
|
|
request_Id |
string |
The ID generated by the system for this call. |
|
|
code |
string |
The error code if the request fails. This is ignored on success. Python only |
|
|
message |
string |
The detailed error message if the request fails. This is ignored on success. Python only |
|
|
output |
dict |
The call result. For Qwen models, this includes the output text. |
|
|
usage |
dict |
The metering data for this request. |
|
|
output.text |
string |
The response generated by the model. |
|
|
output.finish_reason |
string |
This is null during generation. If generation stops due to a stop token, the value is `stop`. |
|
|
output.session_id |
string |
The unique ID of the conversation session. |
In a multi-turn conversation, you can use this ID for session persistence. |
|
usage.models[].model_id |
string |
The model invoked by the application for this call. |
|
|
usage.models[].input_tokens |
int |
The number of tokens in the user input text. |
|
|
usage.models[].output_tokens |
int |
The number of tokens in the response generated by the model. |
|
|
output.thoughts[].throught |
string |
The model's thought process result. |
|
|
output.thoughts[].action_type |
string |
The type of execution step returned by the LLM. `api`: Execute an API plugin. `response`: Return the final result. |
|
|
output.thoughts[].action_name |
string |
The name of the action being executed, such as document retrieval or an API plugin. |
|
|
output.thoughts[].action |
string |
The step being executed. |
|
|
output.thoughts[].action_input_stream |
string |
The streaming result of the input parameter. |
|
|
output.thoughts[].action_input |
string |
The input parameters for the plugin. |
|
|
output.thoughts[].response |
string |
The result returned by the model call. |
|
|
output.thoughts[].observation |
string |
The result returned by the retrieval or plugin. |
HTTP API
Description
The application supports API calls that use the standard HTTP and HTTP Server-Sent Events (SSE) protocols. You can choose the protocol that suits your needs.
Prerequisites
-
The Alibaba Cloud Model Studio service is activated. For more information, see Activate the service.
-
An API key is created. For more information, see Obtain an API key.
-
A RAG application is created and enterprise knowledge is uploaded. For more information, see Build a Q&A application with no code and Upload enterprise knowledge.
Submit an API call
POST https://dashscope.aliyuncs.com/api/v1/apps/{YOUR_APP_ID}/completionRequest parameters
|
Parameter-passing method |
Field |
Type |
Required |
Description |
Example |
|
Header |
Content-Type |
String |
Yes |
The request type: application/json |
application/json |
|
Accept |
String |
No |
*/*. Set to `text/event-stream` to enable SSE responses. The default is not set. |
text/event-stream |
|
|
Authorization |
String |
Yes |
The API key. Example: Bearer d1**2a |
Bearer d1**2a |
|
|
X-DashScope-SSE |
String |
No |
Use either this or `Accept: text/event-stream` to enable SSE responses. |
enable |
|
|
X-DashScope-WorkSpace |
String |
No |
The workspace ID. |
ws_ik******RVYCKzt |
|
|
Body |
input.prompt |
String |
Yes |
The instruction that you want the model to execute. Both Chinese and English are supported. |
Which park is closer to me? |
|
input.history |
List |
No |
The conversation history between the user and the model. Each element in the list is a turn in the conversation, formatted as {"user": "user input", "bot": "model output"}. The turns are arranged chronologically. |
"history": [ { "user":"How is the weather today?", "bot":"The weather is nice today. Do you want to go out?" }, { "user":"Do you have any recommendations?", "bot":"I suggest going to the park. Spring is here, and the flowers are beautiful." } ] |
|
|
input.session_id |
String |
No |
The unique ID of a conversation session. If you pass a session_id, the conversation history is recorded in the cloud. The LLM automatically includes the stored conversation history in subsequent calls. Make sure that the session_id is unique. You can use either session_id or history, but not both. |
||
|
input.doc_tag_codes |
String |
No |
A list of document tag codes. When you pass a list of tag codes, the retrieval process is limited to the documents associated with those tags. |
["471d*******3427", "881f*****0c232"] |
|
|
parameters.seed |
Integer |
No |
The random number seed used for generation. This controls the randomness of the model's output. The seed must be an unsigned 64-bit integer. The default value is 1234. When a seed is used, the model tries to produce the same or similar results, but identical results are not guaranteed for every generation. |
65535 |
|
|
parameters.top_p |
Float |
No |
The probability threshold for nucleus sampling. For example, a value of 0.2 means that only the tokens with a cumulative probability of 0.2 or higher are kept as the candidate set for random sampling. The value must be in the range of (0, 1.0). A higher value increases randomness, while a lower value decreases randomness. The default value is 0.2. Do not set the value to 1 or higher. |
0.2 |
|
|
parameters.top_k |
Integer |
No |
The size of the candidate set for sampling. For example, a value of 50 means that only the 50 tokens with the highest scores are included in the candidate set for random sampling. A higher value increases randomness, while a lower value increases determinism. Note: If the top_k parameter is empty or its value is greater than 100, the top_k policy is not used, and only the top_p policy is in effect. The default is empty. |
50 |
|
|
parameters.temperature |
Float |
No |
Controls the degree of randomness and diversity. The temperature value smooths the probability distribution of candidate words. A higher temperature value flattens the distribution, allowing less probable words to be selected and making the output more diverse. A lower temperature value sharpens the distribution, making more probable words more likely to be selected and making the output more deterministic. Valid values: [0, 2). The system default is 1.0. A value of 0 is not recommended because it is meaningless. |
1.0 |
|
|
parameters.has_thoughts |
Bool |
No |
Specifies whether to output information about the retrieval and recall process. If enabled, the response includes details about the document retrieval, recall, and model inference processes. |
Response parameters
|
Field |
Type |
Description |
Example |
|
status_code |
int |
A value of 200 (HTTPStatus.OK) indicates that the request was successful. Otherwise, the request failed. You can get the error code from the `code` field and the detailed error message from the `message` field. Note This field is for Python only. In Java, a failure throws an exception that contains the code and message. |
200 |
|
request_Id |
string |
The ID generated by the system for this call. |
33dcf25a-******-8b711f15614e |
|
code |
string |
The error code if the request fails. This is ignored on success. |
|
|
message |
string |
The detailed error message if the request fails. This is ignored on success. |
|
|
output.text |
string |
The response generated by the model. |
|
|
output.finish_reason |
string |
This is null during generation. If generation stops due to a stop token, the value is `stop`. |
|
|
output.session_id |
string |
The unique ID of the conversation session. |
In a multi-turn conversation, you can use this ID for session persistence. |
|
usage.models[].model_id |
string |
The model invoked by the application for this call. |
|
|
usage.models[].input_tokens |
int |
The number of tokens in the user input text. |
|
|
usage.models[].output_tokens |
int |
The number of tokens in the response generated by the model. |
|
|
output.thoughts[].throught |
string |
The model's thought process result. |
|
|
output.thoughts[].action_type |
string |
The type of execution step returned by the LLM. `api`: Execute an API plugin. `response`: Return the final result. |
|
|
output.thoughts[].action_name |
string |
The name of the action being executed, such as document retrieval or an API plugin. |
|
|
output.thoughts[].action |
string |
The step being executed. |
|
|
output.thoughts[].action_input_stream |
string |
The streaming result of the input parameter. |
|
|
output.thoughts[].action_input |
string |
The input parameters for the plugin. |
|
|
output.thoughts[].response |
string |
The result returned by the model call. |
|
|
output.thoughts[].observation |
string |
The result returned by the retrieval or plugin. |
Request example (SSE disabled)
The following example shows a script that uses a cURL command to call a RAG application with SSE disabled.
Replace `YOUR_API_KEY` with your API key and `YOUR_APP_ID` with your app ID to ensure the code runs correctly.
curl --location 'https://dashscope.aliyuncs.com/api/v1/apps/{YOUR_APP_ID}/completion' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--data '{
"input": {
"prompt": "How to cook braised pig's feet with potatoes?"
},
"parameters": {},
"debug": {}
}' --verboseResponse example (SSE disabled)
{
"output": {
"finish_reason": "stop",
"session_id": "a08c1b4e******0c4513db9eea4",
"text": "Braised pig's feet with potatoes is a delicious and nutritious home-style dish. Here is a simple recipe:\n\n**Ingredients:**\n1. 500 g pig's feet (trotters)\n2. 2-3 potatoes\n3. 3-4 slices of ginger\n4. 1 scallion\n5. 2 star anises\n6. 1 small piece of cinnamon bark\n7. 2 bay leaves\n8. Cooking wine, to taste\n9. Light soy sauce and dark soy sauce, to taste\n10. Rock sugar, to taste\n11. Water, as needed\n12. Salt, to taste\n\n**Steps:**\n1. **Prepare the pig's feet**: Chop the pig's feet into small pieces, blanch them in boiling water to remove blood and impurities, then rinse with clean water and set aside.\n \n2. **Caramelize the sugar**: Add a small amount of oil to a pot, add the rock sugar, and cook over low heat until it melts into a red, foamy liquid. Add the blanched pig's feet and stir-fry until they are evenly coated with the caramel.\n\n3. **Braise**: Add the sliced ginger, scallion sections, star anise, cinnamon, and bay leaves. Stir-fry until fragrant. Add the cooking wine, light soy sauce, and dark soy sauce for color. Then, add enough hot water to cover the pig's feet.\n\n4. **Simmer the pig's feet**: Bring to a boil over high heat, skim off any foam, then reduce the heat to medium-low and simmer for about 40 minutes until the pig's feet are tender.\n\n5. **Add the potatoes**: When the pig's feet are about 70-80% cooked, peel and chop the potatoes, add them to the pot, and continue to simmer for about 20 more minutes until the potatoes are cooked through and can be easily pierced with a chopstick.\n\n6. **Season**: Finally, add salt to taste and simmer for a few more minutes to let the flavors meld.\n\n7. **Serve**: When the sauce has thickened and both the potatoes and pig's feet are fully cooked, garnish with chopped scallions or cilantro, then turn off the heat and serve.\n\nThis is the basic recipe for braised pig's feet with potatoes. The cooking time may vary depending on the tenderness of the pig's feet and your personal preference. Adjust as needed."
},
"usage": {
"models": [
{
"output_tokens": 456,
"model_id": "qwen-max",
"input_tokens": 64
}
]
},
"request_id": "99432adc-8b15-953f-afba-fd0895a68773"
}Request example (SSE enabled)
The following example shows a script that uses a cURL command to call a RAG application with SSE enabled.
Replace `YOUR_API_KEY` with your API key and `YOUR_APP_ID` with your app ID to ensure the code runs correctly.
curl --location 'https://dashscope.aliyuncs.com/api/v1/apps/{YOUR_APP_ID}/completion' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--header 'X-DashScope-SSE: enable' \
--data '{
"input": {
"prompt": "How to cook braised pig's feet with potatoes?"
},
"parameters": {},
"debug": {}
}' --verboseResponse example (SSE enabled)
id:1
event:result
:HTTP_STATUS/200
data:{"output":{"session_id":"2c502d4df28******f00488c10da4","finish_reason":"null","text":"potato"},"usage":{"models":[{"input_tokens":64,"output_tokens":1,"model_id":"qwen-max"}]},"request_id":"d9abe8f8-5be6-9118-9232-8c27b9ff536c"}
id:2
event:result
:HTTP_STATUS/200
data:{"output":{"session_id":"2c502d4df28******f00488c10da4","finish_reason":"null","text":"potato stew"},"usage":{"models":[{"input_tokens":64,"output_tokens":2,"model_id":"qwen-max"}]},"request_id":"d9abe8f8-5be6-9118-9232-8c27b9ff536c"}
id:3
event:result
:HTTP_STATUS/200
data:{"output":{"session_id":"2c502d4df28******f00488c10da4","finish_reason":"null","text":"potato stew pork"},"usage":{"models":[{"input_tokens":64,"output_tokens":3,"model_id":"qwen-max"}]},"request_id":"d9abe8f8-5be6-9118-9232-8c27b9ff536c"}
... ... ... ...
... ... ... ...
id:7
event:result
:HTTP_STATUS/200
data:{"output":{"session_id":"2c502d4df28******f00488c10da4","finish_reason":"null","text":"Braised pork trotters with potatoes is a delicious and nutritious home-style dish. Below is a simple recipe:\n\n**Ingredients:**\n1. Pork"},"usage":{"models":[{"input_tokens":64,"output_tokens":32,"model_id":"qwen-max"}]},"request_id":"d9abe8f8-5be6-9118-9232-8c27b9ff536c"}Request example (workspace)
The following example shows a script that uses a cURL command to call a RAG application in a specified workspace.
Replace `YOUR_API_KEY` with your API key, `YOUR_APP_ID` with your app ID, and `YOUR_WORKSPACE` with your workspace ID to ensure the code runs correctly.
curl --location 'https://dashscope.aliyuncs.com/api/v1/apps/{YOUR_APP_ID}/completion' \
--header 'Authorization: Bearer {YOUR_API_KEY}' \
--header 'Content-Type: application/json' \
--header 'X-DashScope-WorkSpace: {YOUR_WORKSPACE}' \
--data '{
"input": {
"prompt": "How to cook braised pig's feet with potatoes?"
},
"parameters": {},
"debug": {}
}' --verboseResponse example (workspace)
{
"output": {
"finish_reason": "stop",
"session_id": "a08c1b4e******0c4513db9eea4",
"text": "Braised pig's feet with potatoes is a delicious and nutritious home-style dish. Here is a simple recipe:\n\n**Ingredients:**\n1. 500 g pig's feet (trotters)\n2. 2-3 potatoes\n3. 3-4 slices of ginger\n4. 1 scallion\n5. 2 star anises\n6. 1 small piece of cinnamon bark\n7. 2 bay leaves\n8. Cooking wine, to taste\n9. Light soy sauce and dark soy sauce, to taste\n10. Rock sugar, to taste\n11. Water, as needed\n12. Salt, to taste\n\n**Steps:**\n1. **Prepare the pig's feet**: Chop the pig's feet into small pieces, blanch them in boiling water to remove blood and impurities, then rinse with clean water and set aside.\n \n2. **Caramelize the sugar**: Add a small amount of oil to a pot, add the rock sugar, and cook over low heat until it melts into a red, foamy liquid. Add the blanched pig's feet and stir-fry until they are evenly coated with the caramel.\n\n3. **Braise**: Add the sliced ginger, scallion sections, star anise, cinnamon, and bay leaves. Stir-fry until fragrant. Add the cooking wine, light soy sauce, and dark soy sauce for color. Then, add enough hot water to cover the pig's feet.\n\n4. **Simmer the pig's feet**: Bring to a boil over high heat, skim off any foam, then reduce the heat to medium-low and simmer for about 40 minutes until the pig's feet are tender.\n\n5. **Add the potatoes**: When the pig's feet are about 70-80% cooked, peel and chop the potatoes, add them to the pot, and continue to simmer for about 20 more minutes until the potatoes are cooked through and can be easily pierced with a chopstick.\n\n6. **Season**: Finally, add salt to taste and simmer for a few more minutes to let the flavors meld.\n\n7. **Serve**: When the sauce has thickened and both the potatoes and pig's feet are fully cooked, garnish with chopped scallions or cilantro, then turn off the heat and serve.\n\nThis is the basic recipe for braised pig's feet with potatoes. The cooking time may vary depending on the tenderness of the pig's feet and your personal preference. Adjust as needed."
},
"usage": {
"models": [
{
"output_tokens": 456,
"model_id": "qwen-max",
"input_tokens": 64
}
]
},
"request_id": "99432adc-8b15-953f-afba-fd0895a68773"
}Error response example
If an error occurs during the request, the output includes a `code` and a `message` that indicate the cause of the error.
{"code":"InvalidApiKey","message":"Invalid API-key provided.","request_id":"2637fcf9-32b1-9f4e-b0e9-1724d4aea00e"}Status codes
For more information about the status codes returned by the service invocation, see Error messages.