Messages - Alibaba Cloud Model Studio

本文詳細闡述了Assistant API中Message類的各項功能，涵蓋了訊息的建立、列舉、檢索、修改等操作。

函數名	類型
create	建立message 類
retrieve	檢索message類
modify	修改message類
list	列出message類

建立訊息

HTTP

程式碼範例

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/threads/thread_e99a9fe7-0433-426f-98ad-a5139c36579c/messages' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "role": "user",
    "content": "你是誰",
    "metadata": {}
}'

輸入參數

輸入參數名字	輸入參數的描述	參數類型	是否必須
thread id	message 所傳入的thread id	str	是
content	message的具體資訊	str	是
role	傳入資訊的角色。目前只支援role = “user"	str	否
metadata	其他相關資訊	str	否

返回結果

{
    "id": "message_f1933671-19e1-4162-ad25-7326165123e1",
    "object": "thread.message",
    "created_at": 1711508433283,
    "thread_id": "thread_e99a9fe7-0433-426f-98ad-a5139c36579c",
    "assistant_id": "",
    "run_id": "",
    "role": "user",
    "content": [
        {
            "type": "text",
            "text": {
                "value": "你是誰",
                "annotations": []
            }
        }
    ],
    "metadata": {},
    "from": "",
    "name": "",
    "plugin_call": {},
    "tool_calls": [],
    "status": {},
    "request_id": "b3ad40b9-f052-9665-a064-dab11c34625f"
}

輸出參數

輸出message類，並包含除了使用者輸入以外參數的其他額外欄位：

id：message id
request_id：請求id

SDK

程式碼範例

Python

from dashscope import Messages
import dashscope
import os

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
msg = Messages.create(
    'the_thread_id',
    # 建議您優先配置環境變數。若沒有配置環境變數，請用百鍊API Key將下行替換為：api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    content='The message content.',
    role='user',
    metadata={'key': 'value'}
)

Java

import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.InvalidateParameter;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.threads.messages.Messages;
import com.alibaba.dashscope.threads.messages.TextMessageParam;
import com.alibaba.dashscope.threads.messages.ThreadMessage;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    static {
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
        // create a message to thread
        Messages messages = new Messages();
        TextMessageParam param = TextMessageParam.builder()
                // 建議您優先配置環境變數。若沒有配置環境變數，請用百鍊API Key將下行替換為：apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .role("user")
                .content("如何做出美味的牛肉燉馬鈴薯？")
                .build();
        ThreadMessage message = messages.create("threadId", param);
    }
}

輸入參數

參數	類型	預設值	說明
thread_id	str	-	Thread id
content	str	-	訊息內容
role	str	'user'	Message的role，預設user
metadata	Dict	None	與該Message關聯的key/value資訊
workspace	str	None	阿里雲百鍊的Workspace ID，僅當 api_key 為子業務空間 API Key 時才需要傳入。
api_key	str	None	阿里雲百鍊的API Key，建議您配置API Key到環境變數。

返回結果

結果為Message對象，json化內容為：

{
    "assistant_id": "",
    "content": [
        {
            "text": {
                "value": "sdhafjdasf"
            },
            "type": "text"
        }
    ],
    "created_at": 1711345341301,
    "display": true,
    "from": "",
    "gmt_crete": "2024-03-25 13:42:21",
    "gmt_update": "2024-03-25 13:42:21",
    "id": "message_05494921-a646-484e-85fc-76329acba842",
    "metadata": {
        "key": "value"
    },
    "name": "",
    "object": "thread.message",
    "plugin_call": {},
    "request_id": "631de0b3-7e50-9c9e-8444-0924d1b7e7a5",
    "role": "user",
    "run_id": "",
    "status": {},
    "status_code": 200,
    "thread_id": "thread_f1e7737e-b045-479f-99d1-510db49d535b",
    "tool_calls": []
}

輸出參數

欄位名	欄位類型	欄位描述
status_code	int	為調用http status code，200表示調用成功，其他表示調用出錯
id	str	Message id，為uuid字串
content	List[dict]	訊息內容
content.type	str	content內容類型，如text
content.text	dict	content內容
content.text.value	str	content text value
metadata	Dict	和這個Message關聯的key/value資訊
tool_calls	Dict	調用tool資訊
plugin_call	Dict	調用plugin 資訊
created_at	timestamp	assistant建立時間
gmt_created	datetime	2024-03-22 17:12:31
gmt_modified	datetime	2024-03-22 17:12:31
code	str	表示請求失敗，表示錯誤碼，成功忽略。 python only
message	str	失敗，表示失敗詳細資料，成功忽略。 python only

訊息列表

HTTP

程式碼範例

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/threads/thread_e99a9fe7-0433-426f-98ad-a5139c36579c/messages?limit=2&order=desc' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

輸入參數

輸入參數名字	輸入參數的描述	參數類型	是否必須
thread id	message 所傳入的thread id	str	是
limit	建立message的數量	int	否
order	按照建立時間升序或降序	str	否（預設為”desc“）

返回結果

{
    "object": "list",
    "data": [
        {
            "id": "message_f1933671-19e1-4162-ad25-7326165123e1",
            "object": "thread.message",
            "created_at": 1711508433283,
            "thread_id": "thread_e99a9fe7-0433-426f-98ad-a5139c36579c",
            "assistant_id": "",
            "run_id": "",
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": {
                        "value": "你是誰",
                        "annotations": []
                    }
                }
            ],
            "metadata": {},
            "from": "",
            "name": "",
            "plugin_call": {},
            "tool_calls": [],
            "status": {}
        }
    ],
    "first_id": "message_f1933671-19e1-4162-ad25-7326165123e1",
    "last_id": "message_f1933671-19e1-4162-ad25-7326165123e1",
    "has_more": false,
    "request_id": "78f7d607-4a9a-90c6-8040-d3f81c84d60a"
}

輸出參數

輸出List message類，並包含除了使用者輸入以外參數的其他額外欄位：

多個message 組成的列表

SDK

程式碼範例

Python

from dashscope import Messages
import dashscope
import os

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

messages = Messages.list(
    'thread_id',
    # 建議您優先配置環境變數。若沒有配置環境變數，請用百鍊API Key將下行替換為：api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    limit=1,
    order='desc'
)

Java

import com.alibaba.dashscope.common.GeneralListParam;
import com.alibaba.dashscope.common.ListResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.InvalidateParameter;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.threads.messages.Messages;
import com.alibaba.dashscope.threads.messages.ThreadMessage;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    static {
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
        Messages messages = new Messages();
        // 建議您優先配置環境變數。若沒有配置環境變數，請用百鍊API Key將下行替換為：apiKey("sk-xxx")
        GeneralListParam listThreadMessages = GeneralListParam.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .build();
        ListResult<ThreadMessage> message = messages.list("threadId", listThreadMessages);
    }
}

輸入參數

參數	類型	預設值	說明
thread_id	str	-	指定要查詢的thread id。
limit	int	None	要檢索的訊息數。
order	str	None	按 created_at 排序的順序。
workspace	str	None	阿里雲百鍊的Workspace ID，僅當 api_key 為子業務空間 API Key 時才需要傳入。
api_key	str	None	阿里雲百鍊的API Key，建議您配置API Key到環境變數。

輸出參數

欄位名	欄位類型	欄位描述
has_more	bool	是否還有更多訊息可以檢索。
last_id	str	返回的訊息列表中最後一個訊息的 ID。
first_id	str	返回的訊息列表中第一個訊息的 ID。
data	list[Message]	Message對象列表。

檢索訊息

HTTP

程式碼範例

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/threads/thread_e99a9fe7-0433-426f-98ad-a5139c36579c/messages/message_ea26d29d-4509-490e-98e9-9f6238bd821b' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

輸入參數

輸入參數名字	輸入參數的描述	參數類型	是否必須
thread id	待檢索的message 所傳入的thread id	str	是
message_id	待檢索的message_id	str	是

返回結果

{
    "id": "message_ea26d29d-4509-490e-98e9-9f6238bd821b",
    "object": "thread.message",
    "created_at": 1711508622598,
    "thread_id": "thread_e99a9fe7-0433-426f-98ad-a5139c36579c",
    "assistant_id": "",
    "run_id": "",
    "role": "user",
    "content": [
        {
            "type": "text",
            "text": {
                "value": "你好",
                "annotations": []
            }
        }
    ],
    "metadata": {},
    "from": "",
    "name": "",
    "plugin_call": {},
    "tool_calls": [],
    "status": {},
    "request_id": "4d5ce962-91c3-9edb-87f7-00bbf985135e"
}

輸出參數

輸出檢索到的message類，並包含除了使用者輸入以外參數的其他額外欄位：

id：message_id
request_id：請求id

SDK

程式碼範例

Python

from dashscope import Messages
import dashscope
import os

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

message = Messages.retrieve(
    'message_id',
    # 建議您優先配置環境變數。若沒有配置環境變數，請用百鍊API Key將下行替換為：api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    thread_id='thread_id'
)

Java

import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.InvalidateParameter;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.threads.messages.Messages;
import com.alibaba.dashscope.threads.messages.ThreadMessage;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    static {
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
        Messages messages = new Messages();
        // 建議您優先配置環境變數。若沒有配置環境變數，請用百鍊API Key將下行替換為：apiKey("sk-xxx")
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        ThreadMessage message = messages.retrieve("threadId", "messageId", apiKey);
    }
}

輸入參數

參數	類型	預設值	說明
message_id	str	-	指定要查詢的Message id
thread_id	str	-	指定要查詢的Message所屬Thread id
workspace	str	None	阿里雲百鍊的Workspace ID，僅當 api_key 為子業務空間 API Key 時才需要傳入。
api_key	str	None	阿里雲百鍊的API Key，建議您配置API Key到環境變數。

輸出參數

參考 create 結果

修改訊息

HTTP

程式碼範例

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/threads/thread_e99a9fe7-0433-426f-98ad-a5139c36579c/messages/message_ea26d29d-4509-490e-98e9-9f6238bd821b' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "metadata": {
        "modified": "true",
        "user": "abc123"
    }
}'

輸入參數

輸入參數名字	輸入參數的描述	參數類型	是否必須
thread_id	待修改的thread_id	str	是
message_id	待修改的message_id	str	是
metadata	中繼資料	dict

返回結果

{
    "id": "message_ea26d29d-4509-490e-98e9-9f6238bd821b",
    "object": "thread.message",
    "created_at": 1711508622598,
    "thread_id": "thread_e99a9fe7-0433-426f-98ad-a5139c36579c",
    "assistant_id": "",
    "run_id": "",
    "role": "user",
    "content": [
        {
            "type": "text",
            "text": {
                "value": "你好",
                "annotations": []
            }
        }
    ],
    "metadata": {
        "modified": "true",
        "user": "abc123"
    },
    "from": "",
    "name": "",
    "plugin_call": {},
    "tool_calls": [],
    "status": {},
    "request_id": "7877b011-cb94-9df1-9add-dc42b7d611f6"
}

輸出參數

輸出修改後的message類，並包含除了使用者輸入以外參數的其他額外欄位：

id ：message_id
request_id ：請求id

SDK

程式碼範例

Python

from dashscope import Messages
import dashscope
import os

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

thread = Messages.update(
    'message_id',
    # 建議您優先配置環境變數。若沒有配置環境變數，請用百鍊API Key將下行替換為：api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    thread_id='the_message_thread_id',
    metadata={'key': 'value'}
)

Java

import java.util.Collections;
import com.alibaba.dashscope.common.UpdateMetadataParam;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.InvalidateParameter;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.threads.messages.Messages;
import com.alibaba.dashscope.utils.Constants;

public class Main {
    static {
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    public static void main(String[] args) throws ApiException, NoApiKeyException, InputRequiredException, InvalidateParameter, InterruptedException {
        Messages messages = new Messages();
        // 建議您優先配置環境變數。若沒有配置環境變數，請用百鍊API Key將下行替換為：apiKey("sk-xxx")
        UpdateMetadataParam updateMetadataParam = UpdateMetadataParam.builder()
                .metadata(Collections.singletonMap("key", "value"))
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .build();
        messages.update("thread_id", "message_Id", updateMetadataParam);
    }
}

輸入參數

參數	類型	預設值	說明
message_id	str	-	指定要更新的Message id
thread_id	str	-	指定要更新的Message所屬Thread id
metadata	Dict	None	Thread關聯資訊
workspace	str	None	阿里雲百鍊的Workspace ID，僅當 api_key 為子業務空間 API Key 時才需要傳入。
api_key	str	None	阿里雲百鍊的API Key，建議您配置API Key到環境變數。

輸出參數

參考 create 結果

錯誤碼

如果 Assistant API 呼叫失敗並返回報錯資訊，請參見錯誤資訊進行解決。