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

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

重要

アシスタント API は非推奨になりつつあります。代替として Responses API に移行してください。Responses API には、複数の組み込みツールが含まれており、マルチターンコンテキスト管理をサポートしています。

概要：アシスタント 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	スレッド名	string	いいえ

レスポンス

{
    "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 キーを環境変数として設定することを推奨します。設定しない場合は、次の行を api_key="sk-xxx" に置き換え、ご利用の Model Studio API キーを使用してください。
    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 キーを環境変数として設定することを推奨します。設定しない場合は、次の行を apiKey("sk-xxx") に置き換え、ご利用の Model Studio API キーを使用してください。
        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 形式のオブジェクトを示しています：

{
    "created_at": 1711338305031,
    "id": "thread_97934051-2c15-44bf-97de-310039d873f9",
    "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	スレッドが作成された時間。
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 キーを環境変数として設定することを推奨します。設定しない場合は、次の行を api_key="sk-xxx" に置き換え、ご利用の Model Studio API キーを使用してください。
    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 キーを環境変数として設定することを推奨します。設定しない場合は、次の行を apiKey("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 キーを環境変数として設定することを推奨します。設定しない場合は、次の行を api_key="sk-xxx" に置き換え、ご利用の Model Studio API キーを使用してください。
    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 キーを環境変数として設定することを推奨します。設定しない場合は、次の行を apiKey("sk-xxx") に置き換え、ご利用の Model Studio API キーを使用してください。
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .build();
        threads.update("thread_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 キーは環境変数として設定することを推奨します。

レスポンスパラメーター

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

スレッドの削除

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	文字列	はい

レスポンス

{
    "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 キーを環境変数として設定することを推奨します。設定しない場合は、次の行を api_key="sk-xxx" に置き換え、ご利用の Model Studio API キーを使用してください。
    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 キーを環境変数として設定することを推奨します。設定しない場合は、次の行を apiKey("sk-xxx") に置き換え、ご利用の Model Studio API キーを使用してください。
        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	削除の確認

エラーコード

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