Skip to main content

アシスタント API の使用開始 (非推奨)

アシスタント API は、会話メッセージやツールの呼び出しを簡単に管理できる一連の開発ツールを提供します。このトピックでは、お絵かきアシスタントをゼロから構築する例を通して、アシスタント API の基本的なエンコーディングメソッドを素早く習得できるよう支援します。

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

一般的なプロセス

以下は、エージェントアプリケーション (アシスタント) を構築するための一般的なプロセスです。
  1. アシスタントの作成：アシスタントを作成する際に、モデルを選択し、命令を提供し、コードインタープリター関数呼び出しなどのツールを追加します。
  2. スレッドの作成：ユーザーが会話を開始する際に、会話履歴を追跡するためのセッションスレッドを作成します。
  3. スレッドへのメッセージの送信：ユーザーのメッセージを会話に追加します。
  4. Run の開始：セッションスレッドでアシスタントを実行します。アシスタントはメッセージを解析し、適切なツールやサービスを呼び出し、応答を生成して返します。

シナリオ例

テキスト生成モデルは、単独で画像を生成することはできません。通常、テキストを画像に変換するには、特定の Text-to-Image モデルが必要です。アシスタント API で作成されたエージェントアプリケーションは、ユーザーが提供した説明的な言葉を自動的に最適化し、Text-to-Image ツールを呼び出して高品質な画像を生成できます。例えば、ペットの猫のリアルな画像を生成するために、基本的な説明を提供するだけで済みます。お絵かきアシスタントは自動的にプロンプトを洗練させ、それを直接 Text-to-Image ツールに渡して、画像作成タスクを効率的に完了します。

操作手順

以下の手順では、非ストリーミング出力モードでの Python を使用したプロセスを説明します。ストリーミング出力と非ストリーミング出力の両方に対応した完全な Python および Java SDK のコードについては、このトピックの最後にある完全なコードをご参照ください。
image

ステップ 1：開発環境の準備

  • プラグイン使用権限の申請：まず、画像生成プラグインの使用権限を申請する必要があります。Model Studio コンソールの [プラグイン] ページに移動し、対応するカードの プラグインの申請 をクリックします。
  • Python インタープリター：アシスタント API には Python 3.9 以降が必要です。ご利用の Python のバージョンを確認できます。特定のバージョンの Python をインストールするには、Python のダウンロードをご参照ください。
  • DashScope SDK：最新バージョンの DashScope SDK を使用することを推奨します。右側のコマンドでバージョンを確認できます。特定のバージョンの DashScope SDK をインストールするには、pip を使用します。
  • API キー：アシスタント API には Alibaba Cloud Model Studio の API キーが必要です。API キーはこちらで取得できます。初めて DashScope SDK を使用する際は、機密情報の漏洩を防ぐために、API キーを環境変数として設定することを推奨します。
# Python インタープリターのバージョンを確認します
python --version

# DashScope SDK を確認します
pip list | grep dashscope

# DashScope SDK バージョン 1.17.0 をインストールします
pip install dashscope==1.17.0

ステップ 2：アシスタントの作成

Dashscope SDK をインポートした後、Assistant クラスの create メソッドを使用してアシスタントエージェントを作成します。このプロセスでは、以下の主要なパラメーターを設定します。
  • model：大規模言語モデルの名前。エージェントの LLM を構成するために使用されます。
  • name：エージェントの名前。識別するために使用されます。
  • description：エージェントの機能の説明。
  • instructions：エージェントの役割とタスクを定義する自然言語の命令。
  • tools：エージェントに構成されたツールのリスト。
この例では、お絵かきに特化したアシスタントを構築することが目標です。Text-to-Image ツールは言語理解に対する要求が高いため、アシスタントの意味理解とテキスト生成能力を向上させるために、推論モデルとして Qwen-Max を選択します。エージェントの名前、機能説明、命令などの構成詳細は、添付のコードスニペットに明確に示されています。エージェントの機能性と実用性を高めるために、公式の構築済みプラグインである画像生成を統合します。これにより、アシスタントが受け取ったテキスト記述に基づいて、対応する画像コンテンツを自動的に生成できるようになります。アシスタントは無制限に作成できます。ただし、単一モデルへの頻繁な呼び出しは、レート制限を引き起こす可能性があります。ユースケースに基づいて、アシスタントに異なるモデルを構成することを推奨します。API の使用方法の詳細については、「アシスタント API」をご参照ください。
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# Qwen-Max を使用して新しいお絵かきアシスタントを作成
painting_assistant = dashscope.Assistants.create(
    model='qwen-max',  # 理解を深めるために Qwen-Max モデルを使用。モデルリスト：https://www.alibabacloud.com/help/model-studio/getting-started/models
    name='Art Maestro',  # アシスタント名は「Art Maestro」
    description='An AI assistant specializing in painting and art knowledge.',
    instructions='''あなたは専門のお絵かきアシスタントです。絵画の技法、美術史、創造的なガイダンスに関する詳細な情報を提供してください。''',
    tools=[
        {
            'type': 'text_to_image',  # 説明に基づいて画像を生成するためのツール
            'description': 'このツールを使用して、絵画のスタイル、技法、または芸術の概念の視覚的な例を作成します。'
        }
    ]
)

# アシスタントの ID を出力して作成が成功したことを確認
print(f"Painting assistant 'Art Maestro' created successfully, ID: {painting_assistant.id}")

ステップ 3：スレッドの作成

スレッドは、アシスタント API における重要な概念であり、継続的な会話コンテキストを表します。スレッドを使用すると、ユーザーが新しい会話を開始したときにセッション管理スレッドを作成できます。アシスタントはスレッドを使用して会話全体のコンテキストを理解し、より一貫性のある関連性の高い応答を提供できます。以下を推奨します。
  • 新しいユーザーまたは新しい会話トピックごとに新しいスレッドを作成します。
  • コンテキストを維持する必要がある場合は、同じスレッドを引き続き使用します。
  • コンテキストの混乱を避けるために、会話のトピックが大幅に変わった場合は新しいスレッドを作成することを検討します。
お絵かきアシスタントのシナリオでは、スレッドはユーザーの最初の要求、アシスタントの予備的な提案、ユーザーのフィードバック、そして最終的なお絵かき結果を追跡し、完全な作成プロセスを形成します。これにより、作成プロセス全体の一貫性と追跡可能性が保証されます。API の使用方法の詳細については、「スレッド API」をご参照ください。
from http import HTTPStatus
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# 新しい空のスレッドを作成
thread = dashscope.Threads.create()

# スレッドが正常に作成されたか確認
if thread.status_code == HTTPStatus.OK:
    print(f"Thread created successfully. Thread ID: {thread.id}")
    print("You can now start a painting conversation with the AI assistant.")
else:
    print(f"Thread creation failed. Status code: {thread.status_code}")
    print(f"Error code: {thread.code}")
    print(f"Error message: {thread.message}")

# 注：この空のスレッドは、ラグドール猫や他の絵画の主題に関する将来のメッセージを含む、
# お絵かきプロジェクトの議論のコンテキストを維持するために使用できます。

ステップ 4：スレッドへのメッセージの追加

入力は Message オブジェクトを介して渡されます。アシスタント API は、単一のスレッドに 1 つ以上のメッセージを送信することをサポートしています。Message を作成する際には、以下のパラメーターを考慮してください。
  • スレッドの一意の ID：thread_id
  • メッセージの内容：content
スレッドが受信できるトークンの数に厳密な制限はありませんが、実際に LLM に渡されるトークンの数は、モデルの最大入力長制限に準拠する必要があります。詳細については、各 Qwen シリーズモデルの公式ドキュメントでコンテキスト長に関する情報をご参照ください。このシナリオでは、スレッド内の最初のメッセージとして「ラグドールの絵を描いてください。」を送信します。Message クラスを作成する必要があります。詳細なパラメーター設定は、添付のコードスニペットで提供されています。API の使用方法の詳細については、「メッセージ」をご参照ください。
Messages.create() メソッドが実行されると、メッセージは自動的にスレッドに追加され、スプーリングがトリガーされます。これは、メッセージの作成と送信の両方の操作を同時に完了することに相当し、API のデフォルトの動作です。
from http import HTTPStatus
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# アシスタントに何をするかを伝えるメッセージを作成します。
message = dashscope.Messages.create(thread.id, content='ラグドールの絵を描いてください。')

# メッセージが正常に作成されたか確認
if message.status_code == HTTPStatus.OK:
    print('Message created successfully! Message ID: %s' % message.id)
else:
    print('Message creation failed. Status code: %s, Error code: %s, Error message: %s' % (message.status_code, message.code, message.message))

ステップ 5：Run の作成と実行

ユーザーが特定の Thread にメッセージを割り当てた後、Run を開始して、事前に設定されたアシスタントをアクティブにすることができます。アシスタントは、スレッド内のすべてのメッセージをコンテキストとして使用し、指定されたモデルと利用可能なプラグインを活用して、ユーザーの質問にインテリジェントに応答し、生成された回答をスレッドのメッセージシーケンスに挿入します。このシナリオでは、以下の手順を実行します。
  1. Run オブジェクトを初期化して、お絵かきアシスタントを駆動し、スレッド ID (thread.id) とアシスタント ID (assistant.id) を渡します。
  2. 実行が完了するまで、Run オブジェクトの wait メソッド (Run.wait) を使用します。
  3. メッセージリストメソッド (Messages.list) を使用して、アシスタントが描いたペットの猫の絵を取得します。
この一連の操作により、アシスタントが質問を受け取ってから結果を出力するまでの一連の自動処理フローが保証されます。API の使用方法の詳細については、「Runs API」をご参照ください。
多くのユーザーが同時にモデルを使用している場合があり、処理時間が長くなることがあります。スムーズなプロセスを確保するために、ステータスが「complete」と表示されるまで待ってから次の操作を実行することを推奨します。
from http import HTTPStatus
import json
import dashscope
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# メッセージを実行するための新しい Run を作成
run = dashscope.Runs.create(thread.id, assistant_id=painting_assistant.id)
if run.status_code != HTTPStatus.OK:
    print('Failed to create assistant, Status code: %s, Error code: %s, Error message: %s' % (run.status_code, run.code, run.message))
else:
    print('Assistant created successfully, ID: %s' % run.id)

# Run が完了するか、アクションが必要になるまで待機
run = dashscope.Runs.wait(run.id, thread_id=thread.id)
if run.status_code != HTTPStatus.OK:
    print('Failed to get run status, Status code: %s, Error code: %s, Error message: %s' % (run.status_code, run.code, run.message))
else:
    print(run)

# スレッドメッセージを取得して Run の出力を得る
msgs = dashscope.Messages.list(thread.id)
if msgs.status_code != HTTPStatus.OK:
    print('Failed to get messages, Status code: %s, Error code: %s, Error message: %s' % (msgs.status_code, msgs.code, msgs.message))
else:
    print(json.dumps(msgs, default=lambda o: o.__dict__, sort_keys=True, indent=4))

完全なコード

  • 非ストリーミング出力
  • ストリーミング出力
import dashscope
from http import HTTPStatus
import json
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

def check_status(component, operation):
    if component.status_code == HTTPStatus.OK:
        print(f"{operation} に成功しました。")
        return True
    else:
        print(f"{operation} に失敗しました。ステータスコード： {component.status_code}、エラーコード： {component.code}、エラーメッセージ： {component.message}")
        return False

# 1. 絵画アシスタントを作成
painting_assistant = dashscope.Assistants.create(
    # モデルリスト： https://www.alibabacloud.com/help/model-studio/getting-started/models
    model='qwen-max',
    name='Art Maestro',
    description='AI assistant for painting and art knowledge',
    instructions='''Provide information on painting techniques, art history, and creative guidance.
    Use tools for research and image generation.''',
    tools=[
        {'type': 'text_to_image', 'description': 'For creating visual examples'}
    ]
)

if not check_status(painting_assistant, "アシスタントの作成"):
    exit()

# 2. 新しいスレッドを作成
thread = dashscope.Threads.create()

if not check_status(thread, "スレッドの作成"):
    exit()

# 3. スレッドにメッセージを送信
message = dashscope.Messages.create(thread.id, content='ラグドール猫の絵を描くのを手伝ってください。')

if not check_status(message, "メッセージの作成"):
    exit()

# 4. スレッドでアシスタントを実行
run = dashscope.Runs.create(thread.id, assistant_id=painting_assistant.id)

if not check_status(run, "Run の作成"):
    exit()

# 5. Run の完了を待機
print("アシスタントがリクエストを処理するのを待機しています...")
run = dashscope.Runs.wait(run.id, thread_id=thread.id)

if check_status(run, "Run の完了"):
    print(f"Run が完了しました。ステータス： {run.status}")
else:
    print("Run は完了しませんでした。")
    exit()

# 6. アシスタントの応答を取得して表示
messages = dashscope.Messages.list(thread.id)

if check_status(messages, "メッセージの取得"):
    if messages.data:
        # 最後のメッセージ (アシスタントの応答) のコンテンツを表示
        last_message = messages.data[0]
        print("\nアシスタントの応答：")
        print(json.dumps(last_message, ensure_ascii=False, default=lambda o: o.__dict__, sort_keys=True, indent=4))
    else:
        print("スレッドにメッセージが見つかりません。")
else:
    print("アシスタントの応答の取得に失敗しました。")

# ヒント： このコードは、絵画アシスタントを作成し、ラグドール猫の絵の描き方に関する会話を開始し、アシスタントの回答を表示します。

次のステップ

アシスタント API コンポーネントの詳細なパラメーター説明については、「アシスタント API 開発リファレンス」をご参照ください。