Assistants APIってどんなの？ | WebとかIoTのブログ

はじめに

業務でAssistants APIを使うことになり、理解のために勉強しつつアウトプットしてみることにした

前提

現在Assistants APIはプレビューなので、本番環境へ適用する際には注意が必要

Azure OpenAI Serviceとは

GPT-4oやGPT-4、Embeddingなどの言語モデルに対し、REST APIアクセスができるサービスです。
- ちなみに、Python・JavaScript用のSDKが提供されています
モデルをそのまま利用するだけではなく、ファインチューニングしてより目的に合わせた回答をしやすくしたり、Azure Virtual NetworkやAzure PrivateLinkやマネージドIDを利用して、モデルへの通信を安全にする工夫をすることができます
その他にも、Azureのサービスを活用することで、OpenAIと同じモデルを利用しながらも、エンタープライズ向けとしてふさわしい性能のAI活用システムを構築することができます

Completions APIについて

GPT-4oなどのモデルにアクセスし、回答を求めるAPIです。
文字列、もしくは配列の形でPromptを入力することで、AIモデルによる補完（Completion）を得ることができます。
- temperatureやtop_pなど、モデル側での処理仕様を調整するオプションもあります。
呼び出し例は次の通り
- リクエスト例 POST https://{endpoint}/openai/deployments/{deployment-id}/completions?api-version=2024-06-01 { "prompt": [ "tell me a joke about mango" ], "max_tokens": 32, "temperature": 1.0, "n": 1 }
- レスポンス例 { "body": { "id": "cmpl-7QmVI15qgYVllxK0FtxVGG6ywfzaq", "created": 1686617332, "choices": [ { "text": "es\\n\\nWhat do you call a mango who's in charge?\\n\\nThe head mango.", "index": 0, "finish_reason": "stop", "logprobs": null } ], "usage": { "completion_tokens": 20, "prompt_tokens": 6, "total_tokens": 26 } } }

Completions以外のAPIについて

Completions以外にも、様々なAPIがあります
- Embeddings API( /embeddings)：ベクター化した結果を得られるAPI
  - リクエスト例 POST https://{endpoint}/openai/deployments/{deployment-id}/embeddings?api-version=2024-06-01 { "input": [ "this is a test" ] }
  - レスポンス例 { "body": { "data": [ { "index": 0, "embedding": [ -0.012838088, -0.007421397, -0.017617522, -0.028278312, -0.018666342, 0.01737855, -0.01821495, -0.006950092, -0.009937238, -0.038580645, 0.010674067, 0.02412286, -0.013647936, 0.013189907, 0.0021125758, 0.012406612, 0.020790534, 0.00074595667, 0.008397198, ] } ], "usage": { "prompt_tokens": 4, "total_tokens": 4 } } }
- チャットAPI( /chat/completions )：複数の会話をもとに、文脈を踏まえた回答を求めるAPI
  - リクエスト例 POST https://{endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version=2024-06-01 { "messages": [ { "role": "system", "content": "you're a helpful assistant that talks like a pirate" }, { "role": "user", "content": "can you tell me how to care for a parrot?" } ] }
  - レスポンス例 { "body": { "id": "chatcmpl-7R1nGnsXO8n4oi9UPz2f3UHdgAYMn", "created": 1686676106, "choices": [ { "index": 0, "finish_reason": "stop", "message": { "role": "assistant", "content": "Ahoy matey! So ye be wantin' to care for a fine squawkin' parrot, eh? Well, shiver me timbers, let ol' Cap'n Assistant share some wisdom with ye! Here be the steps to keepin' yer parrot happy 'n healthy:\\n\\n1. Secure a sturdy cage: Yer parrot be needin' a comfortable place to lay anchor! Be sure ye get a sturdy cage, at least double the size of the bird's wingspan, with enough space to spread their wings, yarrrr!\\n\\n2. Perches 'n toys: Aye, parrots need perches of different sizes, shapes, 'n textures to keep their feet healthy. Also, a few toys be helpin' to keep them entertained 'n their minds stimulated, arrrh!\\n\\n3. Proper grub: Feed yer feathered friend a balanced diet of high-quality pellets, fruits, 'n veggies to keep 'em strong 'n healthy. Give 'em fresh water every day, or ye\\u00e2\\u20ac\\u2122ll have a scurvy bird on yer hands!\\n\\n4. Cleanliness: Swab their cage deck! Clean their cage on a regular basis: fresh water 'n food daily, the floor every couple of days, 'n a thorough scrubbing ev'ry few weeks, so the bird be livin' in a tidy haven, arrhh!\\n\\n5. Socialize 'n train: Parrots be a sociable lot, arrr! Exercise 'n interact with 'em daily to create a bond 'n maintain their mental 'n physical health. Train 'em with positive reinforcement, treat 'em kindly, yarrr!\\n\\n6. Proper rest: Yer parrot be needin' \\u00e2\\u20ac\\u2122bout 10-12 hours o' sleep each night. Cover their cage 'n let them slumber in a dim, quiet quarter for a proper night's rest, ye scallywag!\\n\\n7. Keep a weather eye open for illness: Birds be hidin' their ailments, arrr! Be watchful for signs of sickness, such as lethargy, loss of appetite, puffin' up, or change in droppings, and make haste to a vet if need be.\\n\\n8. Provide fresh air 'n avoid toxins: Parrots be sensitive to draft and pollutants. Keep yer quarters well ventilated, but no drafts, arrr! Be mindful of toxins like Teflon fumes, candles, or air fresheners.\\n\\nSo there ye have it, me hearty! With proper care 'n commitment, yer parrot will be squawkin' \\"Yo-ho-ho\\" for many years to come! Good luck, sailor, and may the wind be at yer back!" } } ], "usage": { "completion_tokens": 557, "prompt_tokens": 33, "total_tokens": 590 } } }
- 文字起こしAPI( /audio/transcriptions )：オーディオを文字起こししてテキストにするAPI
  - リクエスト例 POST https://{endpoint}/openai/deployments/{deployment-id}/audio/transcriptions?api-version=2024-06-01 Authorization: Bearer YOUR_API_KEY Content-Type: multipart/form-data; boundary=--multipart-boundary --multipart-boundary Content-Disposition: form-data; name="file"; filename="file.wav" Content-Type: application/octet-stream RIFF..audio.data.omitted --multipart-boundary--
    - ※ “RIFF..audio.data.omitted”に実際のバイナリが入るイメージ
  - レスポンス例 { "text": "これは日本語のオーディオの文字起こし結果です。" }
- 翻訳API( /audio/translations )：オーディオを文字起こし＆英語に翻訳してテキストにするAPI
  - リクエスト例 POST https://{endpoint}/openai/deployments/{deployment-id}/audio/translations?api-version=2024-06-01 Authorization: Bearer YOUR_API_KEY Content-Type: multipart/form-data; boundary=--multipart-boundary --multipart-boundary Content-Disposition: form-data; name="file"; filename="file.wav" Content-Type: application/octet-stream RIFF..audio.data.omitted --multipart-boundary--
  - レスポンス例 { "text": "This is the transcription and translation of the Japanese audio." }
- イメージ生成API( /images/generations )：
  - リクエスト例 POST https://{endpoint}/openai/deployments/{deployment-id}/images/generations?api-version=2024-06-01 { "prompt": "In the style of WordArt, Microsoft Clippy wearing a cowboy hat.", "n": 1, "style": "natural", "quality": "standard" }
  - レスポンス例 { "body": { "created": 1698342300, "data": [ { "revised_prompt": "A vivid, natural representation of Microsoft Clippy wearing a cowboy hat.", "prompt_filter_results": { "sexual": { "severity": "safe", "filtered": false }, "violence": { "severity": "safe", "filtered": false }, "hate": { "severity": "safe", "filtered": false }, "self_harm": { "severity": "safe", "filtered": false }, "profanity": { "detected": false, "filtered": false } }, "url": "<https://dalletipusw2.blob.core.windows.net/private/images/e5451cc6-b1ad-4747-bd46-b89a3a3b8bc3/generated_00.png?se=2023-10-27T17%3A45%3A09Z&>...", "content_filter_results": { "sexual": { "severity": "safe", "filtered": false }, "violence": { "severity": "safe", "filtered": false }, "hate": { "severity": "safe", "filtered": false }, "self_harm": { "severity": "safe", "filtered": false } } } ] } }

Azure OpenAI Serviceで使えるAssitants APIってどんなの？

AIアシスタントを作成し、指示文に基づいて自動選択したツールを利用して、スレッド単位のメッセージ履歴に基づいて回答を可能にする機能
従来のCompletion APIやChat API単体では難しいユースケースに対応することができる
- 文脈を考慮したり、関数呼び出しを組み合わせてワークフロー処理するといった回答には、Completion APIやChat APIでは実装が大変だった
  - Chat APIでは複数メッセージを配列で受け取り、文脈の考慮がしやすくなったものの、それでも難しい部分は残っていた。例えば・・
    - モデルのコンテキスト長を超えないようにメッセージ配列の内容を検査する
    - モデルに合わせてメッセージ配列の内容を圧縮する
    - など
すべてAssistants APIに差し替えればよいかというとそうではない。
- Assitants APIを通して作成したアシスタントに紐づくスレッドのID・実行オブジェクトのIDなどは別途管理する必要があるため、Completion APIやChat APIよりも大変になるケースもある
  - 1メッセージに1回答で十分であればCompletion APIの方がシンプル
  - ほぼ中間処理なくAIモデルに回答してもらうだけならChat APIの方がシンプル
    - tool_choiceパラメータを利用して
- 利用ケースに合わせて、メソッドの使い分け自体の判断をAIモデルに頼るか、ユーザからのユースケース選択に基づくか、その両方か、といった選択をする必要がある

Assistants APIと4つのオブジェクト

AIアシスタントを利用する上での全体像は次の通り
- まず次の4つのオブジェクトについて理解する必要がある
  - アシスタント
  - スレッド
  - メッセージ
  - 実行
実行(run)オブジェクトを操作することで、AIモデルに対して回答を求めることができる
- runオブジェクトを作るには、メッセージが必要。
- メッセージはスレッドに対して作成する必要がある。
- スレッドはアシスタントに対して作成する必要がある。
- そのため、アシスタント→スレッド→メッセージの順でオブジェクトを作成していく必要がある。
- ただ、スレッドに対してメッセージは複数紐づけることができるので、メッセージとrunは1対1ではない
説明
- /completions と /chat/completions APIを利用して、AIモデルに回答を求めることができます。
- /chat/completions APIでは、toolsパラメータでツールを定義し、tool_choiceパラメータでツールの選択方法を指定できます。”auto”設定時、AIモデルが適切なツールとパラメータを選択します。
- ツールの選択はAIモデルに委ねるか、開発者が直接指定します。AIモデルに選択を問い合わせる専用の仕組みはありません。
- /assistants APIを使用すると、ツールの定義と使用方針を事前に設定できます。これにより、個々の対話でのツール選択や使用方法の指定が不要になり、対話の一貫性と効率性が向上します。

参考

Azure OpenAI Service とは – Azure AI services | Microsoft Learn https://learn.microsoft.com/ja-jp/azure/ai-services/openai/overview
Azure リソースのマネージド ID – Managed identities for Azure resources | Microsoft Learn https://learn.microsoft.com/ja-jp/entra/identity/managed-identities-azure-resources/overview
Azure OpenAI Service の REST API リファレンス – Azure OpenAI | Microsoft Learn https://learn.microsoft.com/ja-jp/azure/ai-services/openai/reference#data-plane-inference
Azure OpenAI Service を使ってアシスタントを作成する方法 – Azure OpenAI | Microsoft Learn https://learn.microsoft.com/ja-jp/azure/ai-services/openai/how-to/assistant