乐胖代购免代理版

2024年7月に開催された AOAI DevDay で以外にも注目度が高かった、かつあまり認知されていないように見えた Prompty の入門編をブログにしてみました。

OpenAI のエンドポイントにも対応していますが、ここでは Azure OpenAI の利用を想定して書いています。

Prompty とは
準備
- VS Code の拡張をインストール
- Azure OpenAI のリソース
Prompty のはじめ方
- Prompty ファイルを作る
  - ファイル構成をざっくり解説
- 認証と Prompty の実行
  - env ファイルで構成
  - VS Code の settings で構成
Tips

Prompty とは

Azure OpenAI などの LLM を使うのにエンドポイントをたたく際、プログラムを書いたり Azure OpenAI Studio や Azure AI Studio のプレイグラウンドを利用するのがよくある方法です。

Prompty は、VS Code でプロンプト単位でファイルとして管理するもので、そのままエンドポイントにアクセスできます。そのため、プロンプトを試すのが気軽であり、保存もしやすいです。そしてプログラムからの呼び出しも可能なので、プロンプトの管理をコードとして管理できるようになるのがメリットです。

ちなみに公式のドキュメントがあるのですが、GitHub に repo が公開されて以来 2024年8月時点までずーっと Coming soon のままです🥲

準備

Prompty を利用するには、以下の2つの準備が必要です。

VS Code の拡張をインストール
Azure OpenAI のリソースを作成

VS Code の拡張をインストール

VS Code の Extensions (①) で検索に「prompty」と入力 (②) すると、"Prompty" が出てきます (③) のでインストールします。これで完了。

Azure OpenAI のリソース

Azure OpenAI のリソース作成の操作はここでは触れませんが、Azure Portal や Azure AI Studio から作っておきましょう。

Prompty のはじめ方

prompty のファイルを作って、LLM にアクセスするための構成をすればすぐに実行できます。

Prompty ファイルを作る

まずは prompty とか適当なフォルダを作ってそこを VS Code で起動しましょう。

そして VS Code の Explorer の適当な空欄のところで右クリックすると、"New Prompty" というメニューが出てきますのでそれをクリックします。

出てこない場合は前述の拡張がインストールされていない可能性があるので確認しましょう。

これで "basic.prompty" という、拡張子が prompty のファイルが作られます。

ファイル構成をざっくり解説

このブログを書いてる時点だと、basic.prompty の中身は以下です。

---
name: ExamplePrompt
description: A prompt that uses context to ground an incoming question
authors:
  - Seth Juarez
model:
  api: chat
  configuration:
    type: azure_openai
    azure_endpoint: ${env:AZURE_OPENAI_ENDPOINT}
    azure_deployment: <your-deployment>
  parameters:
    max_tokens: 3000
sample:
  firstName: Seth
  context: >
    The Alpine Explorer Tent boasts a detachable divider for privacy, 
    numerous mesh windows and adjustable vents for ventilation, and 
    a waterproof design. It even has a built-in gear loft for storing 
    your outdoor essentials. In short, it's a blend of privacy, comfort, 
    and convenience, making it your second home in the heart of nature!
  question: What can you tell me about your tents?
---

system:
You are an AI assistant who helps people find information. As the assistant, 
you answer questions briefly, succinctly, and in a personable manner using 
markdown and even add some personal flair with appropriate emojis.

# Customer
You are helping {{firstName}} to find answers to their questions.
Use their name to address them in your responses.

# Context
Use the following context to provide a more personalized response to {{firstName}}:
{{context}}

user:
{{question}}

ファイルの構成は、ヘッダー (--- でくくられたセクション)、system:、user: の3つのセクションに分かれていると思ってください。

ヘッダー (--- でくくられたセクション) - (1-23行目):

model > configuration で Azure OpenAI への接続に関する情報をセットします。
- API Key で認証する場合は api_key を追加して値を書きます。認証関連はまた後述します。
- paramameters で LLM にアクセスする際の parameters (例えば temperature: 0 とか) を構成できます。
sample 内で、システムメッセージに埋め込む変数を定義できます。RAG としてシステムメッセージに埋め込みたい値を定義する感じです。
name/description/authors は LLM でアクセスする際には使われないですが、なんのプロンプトかわかるように書いておくとよいです。

system:

システムメッセージを定義します。前述 --- の中で定義した sample 配下の変数を埋め込むには {{}} で可能です。

user:

ユーザーメッセージ、ようはユーザーからの質問を定義します。これも前述 --- の sample 配下の変数を埋め込むこともできるし、直接記載しても問題ないです。

認証と Prompty の実行

あとは Azure OpenAI と接続するための endpoint や API key などの情報をセットすればすぐに使えます。その情報を定義するのは「.env ファイル」「VS Code の Settings 」を使う2パターン、そしてプラスアルファの推奨設定として API Key は使わず Managed Identity を使う方法がります。

env ファイルで構成

まずは .env ファイルに書く方法からです。

basic.prompty と同じ階層に .env というファイルを作り以下のように書きましょう。値は自身の Azure OpenAI の正しい値をセットします。

AOAI_ENDPOINT=https://xxxxx.openai.azure.com
AOAI_API_KEY=xxxxxxx
AOAI_DEPLOYMENT_NAME=gpt-4o
AOAI_API_VERSION=2024-06-01

あとは、prompty のファイルで model のセクションを以下のように構成します。

model:
  api: chat
  configuration:
    type: azure_openai
    azure_endpoint: ${env:AOAI_ENDPOINT}
    azure_deployment: ${env:AOAI_DEPLOYMENT_NAME}
    api_version: ${env:AOAI_API_VERSION}
    api_key: ${env:AOAI_API_KEY}
※ 以下略

basic.prompty 全体は以下のように構成しました。system message とか書き換えてます。

---
name: ExamplePrompt
description: 関西弁アシスタント
authors:
  - BEACHSIDE
model:
  api: chat
  configuration:
    type: azure_openai
    azure_endpoint: ${env:AOAI_ENDPOINT}
    azure_deployment: ${env:AOAI_DEPLOYMENT_NAME}
    api_version: ${env:AOAI_API_VERSION}
    api_key: ${env:AOAI_API_KEY}
  parameters: 
    max_tokens: 500
    temperature: 1.0
sample:
  firstName: BEACHSIDE
  context: >
    パワーパフガールズは2024年に K-POP アイドルの NewJeans とコラボして話題となりました。
    パワーパフガールズのキャラクターの特徴は以下です。
    ブロッサム: 頭がよくて、正義感が強い、優等生タイプ。 3人の中では、お姉さん的な存在!!作戦を立てるのは、おもにブロッサムの役目で、彼女の指示で、3人は一致団結して、悪に立ち向かう! 長い髪が自慢のおしゃれさん。「氷の息」はブロッサムだけのスーパーパワー!!
    バブルス: かわいいものが大好きな、キュートな声の女の子。ちょっぴり赤ちゃんぽい甘えん坊で、泣き虫だけど、怒らせるとプッツンしちゃって、とっても怖い。パンチのパワーは天下一品。動物が大好きで話すこともできます。お絵かきも大好き!!
    バターカップ: 一番のおてんばで、かわいいとか、か弱いなんて大嫌い。ガンコさと口の悪さは、折り紙つき。その上、口よりも先に手がでちゃうという、ストレートな行動を取るので、困ったものです。目からの光線は破壊力ばつぐん! パワーのもとはお気に入りの毛布!?
  question: すぐに泣くのは誰ですか
---

system:
あなたは関西弁で会話をする AI アシスタントです。
マークダウンを使用して質問に簡潔かつ親しみやすい方法で答え、適切な絵文字で個人的な趣向を加えることもできます。
あなたは {{firstName}} が質問の答えを見つけるのを手伝っています。回答では相手の名前を使って呼びかけてください。

# Context
{{firstName}} に対してよりパーソナライズされた応答を提供するために、次のコンテキストを使用してください。

{{context}}

user:
{{question}}

これで、VS Code の右上にある実行ボタンをクリック (またはコマンドパレットで Prompty: Run) すると、OUTPUT が返ってきます。

簡単に LLM をコールすることができ、試したプロンプトを保存しておくこともできるので、Azure OpenAI Studio とか開くのめんどいと思っている私は、基本的にこっちばかり使っています。

VS Code の settings で構成

さて、先ほどの実行では正常に動作しているのに右下に "Can't find model configuration: default" と出ています。これは、VS Code の Settings の中で "prompty.modelConfigurations" が登録されていないためです。

この設定をしておくと、VS Code の Settings で認証とかの情報を管理でき、.env を用意する必要がなくなります。

設定は、まず VS Code の Settings を開きます (Windows の場合 CTRL + ,、Mac の場合 Command + ,)。

検索で「prompty」と入力 (①) → Extensions の中の "Prompty" をクリック (②) → Propmty: Model Configurations の下にある "Edit in settings.json" をクリックします。

後は、prompty に必要な key と value を設定します。複数定義も可能です。例としてはこんな感じ。

ここで設定した項目は、prompty の model > configuration の中に埋め込まれます。全部設定しておけば configuration のセクションが無くても大丈夫です。オーバーライドしたい項目があればその項目だけを直接 configuration のセクションに書けば OK です。

env ファイルと VS Code の setting で構成が共存している場合で、同じ key がある場合は .env で登録されている値でオーバーライドされます。

VS Code は利用しているデバイス共通で Settings を定義しておくことができる (詳細は以下リンク) ので、この設定をしておくことで、どの PC を使っても同じ設定で使いまわせるので便利です。

Settings Sync in Visual Studio Code

基本的な使い方はこれだけなので気軽に利用できます。

Tips

私が個人的によく使うちょっとした Tips の紹介です。

詳細のログが知りたい

prompty を実行すると、下部に表示される OUTPUT で回答がいい感じに表示されるようになっています。これはデフォルトで Prompty Output が選択されているためです。

ここを下図のように Prompty Output (Verbose) に変えると、REST API のレスポンスを表示することができるので、消費したトークン数など実際のレスポンスに含まれる詳細の情報を確認することが可能です。

データファイルの利用

色々試しているうちに、sample 配下に色々と書くのが辛くなってきます。その場合、外部のファイルから読み込むことが可能です。

まずは、prompty と同じ階層に sample-data.json というファイルを作り、中身は以下とします。

{
  "firstName": "ATSUSHI",
  "context": "パワーパフガールズは2024年に K-POP アイドルの NewJeans とコラボして話題となりました。\nパワーパフガールズのキャラクターの特徴は以下です。\nブロッサム: 頭がよくて、正義感が強い、優等生タイプ。 3人の中では、お姉さん的な存在!!作戦を立てるのは、おもにブロッサムの役目で、彼女の指示で、3人は一致団結して、悪に立ち向かう! 長い髪が自慢のおしゃれさん。「氷の息」はブロッサムだけのスーパーパワー!!\nバブルス: かわいいものが大好きな、キュートな声の女の子。ちょっぴり赤ちゃんぽい甘えん坊で、泣き虫だけど、怒らせるとプッツンしちゃって、とっても怖い。パンチのパワーは天下一品。動物が大好きで話すこともできます。お絵かきも大好き!!\nバターカップ: 一番のおてんばで、かわいいとか、か弱いなんて大嫌い。ガンコさと口の悪さは、折り紙つき。その上、口よりも先に手がでちゃうという、ストレートな行動を取るので、困ったものです。目からの光線は破壊力ばつぐん! パワーのもとはお気に入りの毛布!?",
  "question": "一番の勉強ができるのはだれですか"
}

読み込み方は2パターンありますのでそれぞれ書いていきます。

データファイルの読み方: パターン1

シンプルなパターンで、sample 配下を以下のようにします。

sample: ${file:./sample-data.json}

後は以下のように書くことで、sample-data.json の内容を使えます。

system:
あなたは関西弁で会話をする AI アシスタントです。
マークダウンを使用して質問に簡潔かつ親しみやすい方法で答え、適切な絵文字で個人的な趣向を加えることもできます。
あなたは {{firstName}} が質問の答えを見つけるのを手伝っています。回答では相手の名前を使って呼びかけてください。

# Context
{{firstName}} に対してよりパーソナライズされた応答を提供するために、次のコンテキストを使用してください。

{{context}}

user:
{{question}}

データファイルの読み方: パターン2

この書き方は、ファイルからのデータを読み込む + 直接 prompty に書くのを併用したい場合に使えます。

sample 配下を以下のようにします。

sample:
  data: ${file:./sample-data.json}
  question: 最近コラボしたアイドルは

こう定義すると、ファイルの中は {{data.xxx}} で呼び出し、prompty に直接書いた question は通常通り {{question}} で呼び出します。

system:
あなたは関西弁で会話をする AI アシスタントです。
マークダウンを使用して質問に簡潔かつ親しみやすい方法で答え、適切な絵文字で個人的な趣向を加えることもできます。
あなたは {{data.firstName}} が質問の答えを見つけるのを手伝っています。回答では相手の名前を使って呼びかけてください。

# Context
{{data.firstName}} に対してよりパーソナライズされた応答を提供するために、次のコンテキストを使用してください。

{{data.context}}

user:
{{question}}

細かい設定をするには

基本的にプログラムでできることはほとんど prompty のファイルでも設定ができます。

細かい設定を構成したい場合は、以下リンクに prompty で構成できる定義が書かれているので必要に応じて見るとだいたいできます。

以下のリンクか、以下のリンクからたどれる GitHub の repo の yaml を直接見るかって感じですね。

Prompty File Spec

Managed Identity による認証

Prompty の README とかにも書かれてますが、Managed Identity (日本語だと「マネージド ID」って訳されていたり、「Microsoft Entra ID 認証」と書かれていることあり) の設定を構成しておくことで API key を書く必要がなくなるのでおすすめされています。

IAM に Cognitive Services OpenAI User または Cognitive Services OpenAI Contributor を付与すれば OK ですがリソースによって若干異なります。

Azure OpenAI のリソースの場合はそのリソースの IAM で権限を付与
AI Hub 系のリソース (Azure AI Studio でも使えるリソース) の場合は AI Hub に紐づく Azure AI Services の IAM に権限

全部手順書くのが長くなるなーと思ったのでここでは設定方法は記載しませんが、興味のある方はぜひ構成してみてください。

BEACHSIDE BLOG

Azure と GitHub と C# が好きなエンジニアの個人メモ ( ･ㅂ･)و ̑̑

Prompty 入門 - プロンプトの管理を Prompty で効率的に