作成、取得、削除でアシスタント API スレッドを管理 - Model Studio

このトピックでは、アシスタント API の Thread クラスについて、スレッドの作成、取得、変更、削除の方法を含めて説明します。

概要: アシスタント API の特徴と基本的な使用方法の詳細については、「アシスタント API の概要」をご参照ください。

保持期間: すべての Thread インスタンスは Alibaba Cloud Model Studio サーバーに保存され、有効期限は切れません。スレッド ID を使用してコンテキスト情報を取得できます。

関数名	タイプ
create	Thread クラスを作成します。
retrieve	Thread クラスを取得します。
update	Thread クラスを変更します。
delete	Thread クラスを削除します。

スレッドの作成

HTTP

サンプルコード

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/threads' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "messages": [
        {
            "role": "user",
            "content": "hello"
        }
    ]
}'

リクエストパラメーター

パラメーター	説明	タイプ	必須
messages	スレッドに渡されるメッセージ。	Message クラス	いいえ
metadata	スレッド名	str	いいえ

応答

{
    "id": "thread_e99a9fe7-0433-426f-98ad-a5139c36579c",
    "object": "thread",
    "created_at": 1711448377850,
    "metadata": {},
    "request_id": "dd9489ec-dbdb-95d4-9ff8-cfe29b61db27"
}

応答パラメーター

応答は、次の追加フィールドを持つスレッドオブジェクトを返します:

id: スレッド ID。
request_id: リクエスト ID。

SDK

サンプルコード

Python

import json
from dashscope import Threads
import dashscope
import os

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

thread = Threads.create(
    # API キーを環境変数として設定することを推奨します。設定しない場合は、次の行を Model Studio API キーを使用して api_key="sk-xxx" に置き換えてください。
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    messages=[{"role": "user", "content": "How does AI work? Explain it in simple terms."}]
)
print(json.dumps(thread, default=lambda o: o.__dict__, sort_keys=True, indent=4))

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.AssistantThread;
import com.alibaba.dashscope.threads.ThreadParam;
import com.alibaba.dashscope.threads.Threads;
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 {
        Threads threads = new Threads();
        // API キーを環境変数として設定することを推奨します。設定しない場合は、次の行を Model Studio API キーを使用して apiKey("sk-xxx") に置き換えてください。
        AssistantThread assistantThread = threads.create(ThreadParam.builder()
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .build());
    }
}

リクエストパラメーター

パラメーター	タイプ	デフォルト値	説明
messages	List[Dict]	None	スレッドの初期メッセージ。
metadata	Dict	None	スレッドに関連付けるキーと値のペア。
workspace	str	None	Alibaba Cloud Model Studio のワークスペース ID。このパラメーターは、`api_key` がサブワークスペースの API キーである場合にのみ必須です。
api_key	str	None	Alibaba Cloud Model Studio の API キー。詳細については、「API キーを環境変数として設定する」をご参照ください。

結果

結果は Thread オブジェクトです。次のコードは、JSON フォーマットのオブジェクトを示しています:

{
    "account_id": "sk-6bddfc116de744c3aa1d66893cc87b20",
    "created_at": 1711338305031,
    "gmt_create": "2024-03-25 11:45:05",
    "gmt_update": "2024-03-25 11:45:05",
    "id": "thread_97934051-2c15-44bf-97de-310039d873f9",
    "is_deleted": false,
    "metadata": {},
    "object": "thread",
    "request_id": "982d4b9a-b982-9d53-9c79-a75b32f7168a",
    "status_code": 200
}

応答パラメーター

フィールド	タイプ	説明
status_code	int	HTTP ステータスコード。値 200 は呼び出しが成功したことを示します。その他の値は、呼び出しが失敗したことを示します。
id	str	スレッド ID。UUID 文字列です。
metadata	Dict	スレッドに関連付けられたキーと値のペア。
created_at	timestamp	スレッドが作成された時間。
作成日時	datetime	2024-03-22 17:12:31
GMT 変更	datetime	2024-03-22 17:12:31
code	str	エラーコード。このフィールドは、リクエストが失敗した場合にのみ返されます。このパラメーターは Python 専用です。
message	str	エラーメッセージ。このフィールドは、リクエストが失敗した場合にのみ返されます。 Python のみ

スレッドの取得

HTTP

サンプルコード

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/threads/thread_c7ebb0ca-2e4f-43e5-b223-6e1f8c6fccc7' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

リクエストパラメーター

パラメーター	説明	タイプ	必須
thread_id	取得するスレッドの ID。	str	はい

結果

{
    "id": "thread_c7ebb0ca-2e4f-43e5-b223-6e1f8c6fccc7",
    "object": "thread",
    "created_at": 1711507920700,
    "metadata": {},
    "request_id": "4d4e73ad-15fb-96ac-9262-0643a0fdb5ca"
}

応答パラメーター

応答には、取得されたスレッドオブジェクトが含まれており、これには次の追加フィールドが含まれます:

id：スレッド ID
request_id: リクエストの ID。

SDK

サンプルコード

Python

from dashscope import Threads
import dashscope
import os

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

thread = Threads.retrieve(
    'thread_id',
    # API キーを環境変数として設定することを推奨します。設定しない場合は、次の行を Model Studio API キーを使用して api_key="sk-xxx" に置き換えてください。
    api_key=os.getenv("DASHSCOPE_API_KEY")
)

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.AssistantThread;
import com.alibaba.dashscope.threads.Threads;
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 {
        Threads threads = new Threads();
        // thread_id と apiKey を直接渡します。
        // API キーを環境変数として設定します。設定しない場合は、次の行を "sk-xxx" に置き換え、ご利用の Model Studio API キーを使用してください。
        AssistantThread assistantThread = threads.retrieve(
            "thread_id",
            System.getenv("DASHSCOPE_API_KEY")
        );
    }
}

リクエストパラメーター

パラメーター	タイプ	デフォルト値	説明
thread_id	str	-	クエリするスレッドの ID。
workspace	str	None	Alibaba Cloud Model Studio のワークスペース ID。このパラメーターは、`api_key` がサブワークスペースの API キーである場合にのみ必須です。
api_key	str	None	Alibaba Cloud Model Studio の API キー。詳細については、「API キーを環境変数として設定する」をご参照ください。

応答パラメーター

作成結果をご参照ください。

スレッドの変更

HTTP

サンプルコード

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/threads/thread_c7ebb0ca-2e4f-43e5-b223-6e1f8c6fccc7' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--data '{
    "metadata": {
        "modified": "true",
        "user": "abc123"
    }
}'

リクエストパラメーター

パラメーター	説明	タイプ	必須
thread_id	取得するスレッド ID。	str	はい
metadata	スレッド名	dict	いいえ

結果

{
    "id": "thread_c7ebb0ca-2e4f-43e5-b223-6e1f8c6fccc7",
    "object": "thread",
    "created_at": 1711507920700,
    "metadata": {
        "modified": "true",
        "user": "abc123"
    },
    "request_id": "a9ad63fa-b884-94be-9ec6-5000882de3c4"
}

応答パラメーター

応答は、変更されたスレッドオブジェクトを返し、これには次の追加フィールドが含まれます:

id: thread_id
request_id: リクエスト ID。

SDK

サンプルコード

Python

from dashscope import Threads
import dashscope
import os

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

thread = Threads.update(
    'thread_id',
    # API キーを環境変数として設定することを推奨します。設定しない場合は、次の行を Model Studio API キーを使用して api_key="sk-xxx" に置き換えてください。
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    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.Threads;
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 {
        Threads threads = new Threads();
        UpdateMetadataParam updateMetadataParam = UpdateMetadataParam.builder()
                .metadata(Collections.singletonMap("key", "value"))
                // API キーを環境変数として設定することを推奨します。設定しない場合は、次の行を Model Studio API キーを使用して apiKey("sk-xxx") に置き換えてください。
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .build();
        threads.update("assistant_id", updateMetadataParam);
    }
}

リクエストパラメーター

パラメーター	タイプ	デフォルト値	説明
thread_id	str	-	更新するスレッドの ID。
metadata	Dict	None	スレッドに関連付ける情報。
workspace	str	None	Alibaba Cloud Model Studio のワークスペース ID。このパラメーターは、`api_key` がサブワークスペースの API キーである場合にのみ必須です。
api_key	str	None	Alibaba Cloud Model Studio の API キー。詳細については、「API キーを環境変数として設定する」をご参照ください。

応答パラメーター

この操作は create 操作と同じです。

スレッドの削除

HTTP

サンプルコード

curl --location --request DELETE 'https://dashscope-intl.aliyuncs.com/api/v1/threads/thread_c7ebb0ca-2e4f-43e5-b223-6e1f8c6fccc7' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

リクエストパラメーター

パラメーター	説明	タイプ	必須
id	取得するスレッドの ID	str	はい

結果

{
    "id": "thread_c7ebb0ca-2e4f-43e5-b223-6e1f8c6fccc7",
    "object": "thread.deleted",
    "deleted": true,
    "request_id": "b4edb7b8-5855-9787-b5c3-0374ee2b3b2c"
}

応答パラメーター

スレッドが削除された後のステータスを出力します。

SDK

サンプルコード

Python

from dashscope import Threads
import dashscope
import os

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

thread = Threads.delete(
    'thread_id',
    # API キーを環境変数として設定することを推奨します。設定しない場合は、次の行を Model Studio API キーを使用して api_key="sk-xxx" に置き換えてください。
    api_key=os.getenv("DASHSCOPE_API_KEY")
)

Java

import com.alibaba.dashscope.common.DeletionStatus;
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.Threads;
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 {
        Threads threads = new Threads();
        // API キーを環境変数として設定することを推奨します。設定しない場合は、次の行を Model Studio API キーを使用して apiKey("sk-xxx") に置き換えてください。
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        DeletionStatus assistantThread = threads.delete("thread_id", apiKey);
    }
}

リクエストパラメーター

パラメーター	タイプ	デフォルト値	説明
thread_id	str	-	削除するスレッドの ID。
workspace	str	None	Alibaba Cloud Model Studio のワークスペース ID。このパラメーターは、`api_key` がサブワークスペースの API キーである場合にのみ必須です。
api_key	str	None	Alibaba Cloud Model Studio の API キー。詳細については、「API キーを環境変数として設定する」をご参照ください。

応答パラメーター

フィールド	タイプ	説明
id	str	削除されたオブジェクトの ID。
deleted	bool	これを削除してもよろしいですか？

エラーコード

モデルの呼び出しが失敗し、エラーメッセージが返された場合のトラブルシューティングについては、「エラーメッセージ」をご参照ください。