新しい InterSystems IRIS® Cloud SQL と InterSystems IRIS® Cloud IntegratedML® クラウド製品のユーザーであり、デプロイメントのメトリクスにアクセスして独自の可観測性プラットフォームに送信しようと考えている方のために、メトリクスを Google Cloud Platform Monitoring（旧称 StackDriver）に送信して手っ取り早く行う方法をご紹介します。

クラウドポータルには、概要メトリクス表示用のトップレベルのメトリクスが含まれており、ユーザーに公開されているメトリクスエンドポイントを使用しますが、ある程度探索しなければ、そこにあることには気づきません。

🚩 このアプローチは、「今後名前が付けられる予定の機能」を利用している可能性があるため、それを踏まえると将来性があるものではなく、確実に InterSystemsでサポートされているアプローチではありません。

では、より包括的なセットをエクスポートしたい場合はどうでしょうか？この技術的な記事/例では、メトリクスを取得して可観測性に転送する方法を紹介します。Open Telemetry Collector を使用して、任意のメトリクスターゲットを取得し、任意の可観測性プラットフォーム送信できるように、ニーズに合わせて変更することができます。

上記の結果に導く仕組みは多数の方法で得られますが、ここでは Kubernetes pod を使用して、1 つのコンテナーで Python スクリプトを実行し、もう 1 つのコンテナーで Otel を実行して、メトリクスのプルとプッシュを行います... 自分のやり方を選択することはできますが、この例と記事では、k8s を主人公に Python を使って行います。

手順:

• 前提条件
• Python
• コンテナー
• Kubernetes
• Google Cloud Monitoring

前提要件:

• IRIS®  Cloud SQL の有効なサブスクリプション
• 実行中の 1 つのデプロイメント（オプションで Integrated ML を使用）
• 環境に提供するシークレット

環境変数

ENV IRIS_CLOUDSQL_USER 'user'
ENV IRIS_CLOUDSQL_PASS 'pass'

ENV IRIS_CLOUDSQL_USERPOOLID 'userpoolid'
ENV IRIS_CLOUDSQL_CLIENTID 'clientid'
ENV IRIS_CLOUDSQL_API 'api'

ENV IRIS_CLOUDSQL_DEPLOYMENTID 'deploymentid'

Python:

以下に、クラウドポータルからメトリクスを取得し、それを Otel Collectorが取得するメトリクスとしてローカルにエクスポートする Python ハッキングを示します。

import time
import os
import requests
import json
from warrant import Cognito
from prometheus_client.core import GaugeMetricFamily, REGISTRY, CounterMetricFamily
from prometheus_client import start_http_server
from prometheus_client.parser import text_string_to_metric_families
classIRISCloudSQLExporter(object):definit(self):
self.access_token = self.get_access_token()
self.portal_api = os.environ['IRIS_CLOUDSQL_API']
self.portal_deploymentid = os.environ['IRIS_CLOUDSQL_DEPLOYMENTID']
<span class="hljs-function"><span class="hljs-keyword">def</span> <span class="hljs-title">collect</span><span class="hljs-params">(self)</span>:</span>
    <span class="hljs-comment"># Requests fodder</span>
    url = self.portal_api
    deploymentid = self.portal_deploymentid
    print(url)
    print(deploymentid)

    headers = {
        <span class="hljs-string">'Authorization'</span>: self.access_token, <span class="hljs-comment"># needs to be refresh_token, eventually</span>
        <span class="hljs-string">'Content-Type'</span>: <span class="hljs-string">'application/json'</span>
    }

    metrics_response = requests.request(<span class="hljs-string">"GET"</span>, url + <span class="hljs-string">'/metrics/'</span> + deploymentid, headers=headers)
    metrics = metrics_response.content.decode(<span class="hljs-string">"utf-8"</span>)

    <span class="hljs-keyword">for</span> iris_metrics <span class="hljs-keyword">in</span> text_string_to_metric_families(metrics):
        <span class="hljs-keyword">for</span> sample <span class="hljs-keyword">in</span> iris_metrics.samples:

            labels_string = <span class="hljs-string">"{1}"</span>.format(*sample).replace(<span class="hljs-string">'\''</span>,<span class="hljs-string">"\""</span>)
            labels_dict = json.loads(labels_string)
            labels = []

            <span class="hljs-keyword">for</span> d <span class="hljs-keyword">in</span> labels_dict:
                labels.extend(labels_dict)
            <span class="hljs-keyword">if</span> len(labels) &gt; <span class="hljs-number">0</span>:
                g = GaugeMetricFamily(<span class="hljs-string">"{0}"</span>.format(*sample), <span class="hljs-string">'Help text'</span>, labels=labels)
                g.add_metric(list(labels_dict.values()), <span class="hljs-string">"{2}"</span>.format(*sample))
            <span class="hljs-keyword">else</span>:
                g = GaugeMetricFamily(<span class="hljs-string">"{0}"</span>.format(*sample), <span class="hljs-string">'Help text'</span>, labels=labels)
                g.add_metric([<span class="hljs-string">""</span>], <span class="hljs-string">"{2}"</span>.format(*sample))
            <span class="hljs-keyword">yield</span> g

<span class="hljs-function"><span class="hljs-keyword">def</span> <span class="hljs-title">get_access_token</span><span class="hljs-params">(self)</span>:</span>
    <span class="hljs-keyword">try</span>:
        user_pool_id = os.environ[<span class="hljs-string">'IRIS_CLOUDSQL_USERPOOLID'</span>] <span class="hljs-comment"># isc iss </span>
        username = os.environ[<span class="hljs-string">'IRIS_CLOUDSQL_USER'</span>]
        password = os.environ[<span class="hljs-string">'IRIS_CLOUDSQL_PASS'</span>]
        clientid = os.environ[<span class="hljs-string">'IRIS_CLOUDSQL_CLIENTID'</span>] <span class="hljs-comment"># isc aud </span>
        print(user_pool_id)
        print(username)
        print(password)
        print(clientid)
        
        <span class="hljs-keyword">try</span>:
            u = Cognito(
                user_pool_id=user_pool_id,
                client_id=clientid,
                user_pool_region=<span class="hljs-string">"us-east-2"</span>, <span class="hljs-comment"># needed by warrant, should be derived from poolid doh</span>
                username=username
            )
            u.authenticate(password=password)
        <span class="hljs-keyword">except</span> Exception <span class="hljs-keyword">as</span> p:
            print(p)
    <span class="hljs-keyword">except</span> Exception <span class="hljs-keyword">as</span> e:
        print(e)

    <span class="hljs-keyword">return</span> u.id_token
ifname == 'main':
start_http_server(<span class="hljs-number">8000</span>)
REGISTRY.register(IRISCloudSQLExporter())
<span class="hljs-keyword">while</span> <span class="hljs-keyword">True</span>:
    REGISTRY.collect()
    print(<span class="hljs-string">"Polling IRIS CloudSQL API for metrics data...."</span>)
    <span class="hljs-comment">#looped e loop</span>
    time.sleep(<span class="hljs-number">120</span>)</code></pre>
 

Docker:

FROM python:3.8ADD src /src
RUN pip install prometheus_client
RUN pip install requests
WORKDIR /src
ENV PYTHONPATH '/src/'ENV PYTHONUNBUFFERED=1ENV IRIS_CLOUDSQL_USERPOOLID 'userpoolid'ENV IRIS_CLOUDSQL_CLIENTID 'clientid'ENV IRIS_CLOUDSQL_USER 'user'ENV IRIS_CLOUDSQL_PASS 'pass'ENV IRIS_CLOUDSQL_API 'api'ENV IRIS_CLOUDSQL_DEPLOYMENTID 'deploymentid'RUN pip install -r requirements.txt
CMD ["python" , "/src/iris_cloudsql_exporter.py"]

docker build -t iris-cloudsql-exporter .
docker image tag iris-cloudsql-exporter sween/iris-cloudsql-exporter:latest
docker push sween/iris-cloudsql-exporter:latest

デプロイメント:

k8s、ネームスペースを作成します:

kubectl create ns iris

k8s、シークレットを追加します:

kubectl create secret generic iris-cloudsql -n iris \
    --from-literal=user=$IRIS_CLOUDSQL_USER \
    --from-literal=pass=$IRIS_CLOUDSQL_PASS \
    --from-literal=clientid=$IRIS_CLOUDSQL_CLIENTID \
    --from-literal=api=$IRIS_CLOUDSQL_API \
    --from-literal=deploymentid=$IRIS_CLOUDSQL_DEPLOYMENTID \
    --from-literal=userpoolid=$IRIS_CLOUDSQL_USERPOOLID

otel、構成を作成します:

apiVersion: v1
data:
  config.yaml: |
    receivers:
      prometheus:
        config:
          scrape_configs:
          - job_name: 'IRIS CloudSQL'
              # Override the global default and scrape targets from this job every 5 seconds.
            scrape_interval: 30s
            scrape_timeout: 30s
            static_configs:
                    - targets: ['192.168.1.96:5000']
            metrics_path: /
exporters:
  googlemanagedprometheus:
    project: "pidtoo-fhir"
service:
  pipelines:
    metrics:
      receivers: [prometheus]
      exporters: [googlemanagedprometheus]
kind: ConfigMap
metadata:
name: otel-config
namespace: iris

k8s、otel 構成を configmap としてロードします:

kubectl -n iris create configmap otel-config --from-file config.yaml

k8s、ロードバランサー（確実にオプション）、MetalLB をデプロイします。これはクラスタ外部からグスクレイピングして検査するために行っています。

cat <<EOF | kubectl apply -f -n iris -
apiVersion: v1
kind: Service
metadata:
  name: iris-cloudsql-exporter-service
spec:
  selector:
    app: iris-cloudsql-exporter
  type: LoadBalancer
  ports:
  - protocol: TCP
    port: 5000
    targetPort: 8000
EOF

gcp、Google Cloud へのキーが必要です。サービスアカウントにスコープを設定する必要があります

• roles/monitoring.metricWriter

kubectl -n iris create secret generic gmp-test-sa --from-file=key.json=key.json

k8s; deployment/pod そのもの。2 つのコンテナー:

apiVersion:apps/v1kind:Deploymentmetadata:  name:iris-cloudsql-exporter  labels:    app:iris-cloudsql-exporterspec:  replicas:1  selector:    matchLabels:      app:iris-cloudsql-exporter  template:    metadata:      labels:        app:iris-cloudsql-exporter    spec:      containers:      - name:iris-cloudsql-exporter        image:sween/iris-cloudsql-exporter:latest        ports:        - containerPort:5000        env:        - name:"GOOGLE_APPLICATION_CREDENTIALS"          value:"/gmp/key.json"        - name:IRIS_CLOUDSQL_USERPOOLID          valueFrom:            secretKeyRef:              name:iris-cloudsql              key:userpoolid        - name:IRIS_CLOUDSQL_CLIENTID          valueFrom:            secretKeyRef:              name:iris-cloudsql              key:clientid        - name:IRIS_CLOUDSQL_USER          valueFrom:            secretKeyRef:              name:iris-cloudsql              key:user        - name:IRIS_CLOUDSQL_PASS          valueFrom:            secretKeyRef:              name:iris-cloudsql              key:pass        - name:IRIS_CLOUDSQL_API          valueFrom:            secretKeyRef:              name:iris-cloudsql              key:api        - name:IRIS_CLOUDSQL_DEPLOYMENTID          valueFrom:            secretKeyRef:              name:iris-cloudsql              key:deploymentid      - name:otel-collector        image:otel/opentelemetry-collector-contrib:0.92.0        args:        ---config        -/etc/otel/config.yaml        volumeMounts:        - mountPath:/etc/otel/          name:otel-config        - name:gmp-sa          mountPath:/gmp          readOnly:true        env:        - name:"GOOGLE_APPLICATION_CREDENTIALS"          value:"/gmp/key.json"      volumes:      - name:gmp-sa        secret:          secretName:gmp-test-sa      - name:otel-config        configMap:          name:otel-config

kubectl -n iris apply -f deployment.yaml

実行

特に問題がなければ、ネームスペースを詳しく調べて、状況を確認してみましょう。

✔ GCP と Otel 用の 2 つの configmap

✔ 1 つのロードバランサー

✔ 1 つの pod、2 つのコンテナーが正しくスクレイピングされます

Google Cloud Monitoring

可観測性を調べてメトリクスが正しく受信されていることを確認し、可観測性を高めましょう！

この記事では、IRIS環境におけるPythonプログラミングの基礎について紹介します。

本題に入る前に、重要なトピックである「Pythonの仕組み」について説明します。これは、IRIS環境でPythonを使用して作業する際に起こりうる問題や制限を理解するのに役立ちます。

すべての記事と例は、以下のgitリポジトリで確認できます: iris-python-article

Pythonの仕組み

インタープリター型言語

Pythonはインタープリター型言語であり、コードはランタイム時に1行ずつ実行されます。スクリプトをインポートする場合でも同様です。

これはどういうことでしょうか？ 以下のコードを見てみましょう。

# introduction.py

def my_function():
    print("Hello, World!")

my_function()

このスクリプトを実行すると、Pythonインタープリターはコードを1行ずつ読み取ります。 まず最初に関数 my_function を定義してから、その関数を呼び出すと、コンソールに「Hello, World!」と出力されます。

スクリプトを直接実行している例：

python3 /irisdev/app/src/python/article/introduction.py 

出力は以下のようになります。

Hello, World!

IRIS環境でこのスクリプトをインポートするとどうなるのでしょうか？

Class Article.Introduction Extends %RegisteredObject
{
    ClassMethod Run()
    {
        Set sys = ##class(%SYS.Python).Import("sys")
        do sys.path.append("/irisdev/app/src/python/article")

        do ##class(%SYS.Python).Import("introduction")
    }
}

実行しましょう。

iris session iris -U IRISAPP '##class(Article.Introduction).Run()'

出力が表示されます。

Hello, World!

これは、Pythonインタープリターがコードを解釈しながらインポートするためで、最初に関数を定義し、その後に関数を呼び出します。これはスクリプトを直接実行した場合と同じ動作ですが、実行しているのではなくインポートしています。

⚠️ 重要な注意事項：関数を呼び出さずにスクリプトをインポートしても、何も起こりません。 関数は定義されますが、明示的に呼び出さない限り実行されません。

分かりましたか？ Pythonインタープリターはファイル内のコードを実行しますが、関数を呼び出さなければ、その関数は実行されません。

呼び出さずにインポートする例：

# introduction1.py
def my_function():
    print("Hello, World!")

Pythonインタープリターで実行しましょう。

python3 /irisdev/app/src/python/article/introduction1.py 

出力：

# 関数は定義されていますが、呼び出されていないため、出力はありません

IRIS環境にこのスクリプトをインポートすると：

Class Article.Introduction1 Extends %RegisteredObject
{
    ClassMethod Run()
    {
        Set sys = ##class(%SYS.Python).Import("sys")
        do sys.path.append("/irisdev/app/src/python/article")
        do ##class(%SYS.Python).Import("introduction1")
    }
}

実行しましょう。

iris session iris -U IRISAPP '##class(Article.Introduction1).Run()'

関数は定義されていますが、呼び出されていないため、出力はありません。

🤯この微妙な違いが重要な理由

• Pythonスクリプトをインポートすると、そのスクリプトのコードが実行されます。
  • コードを実行したくない場合があります
• インポートするとスクリプトが実行されているように見えるかもしれませんが、実際には直接実行されているわけではないため、混乱を招く可能性があります。

インポートのキャッシュ

Pythonスクリプトをインポートすると、Pythonインタープリターがインポートされたスクリプトをキャッシュします。 つまり、同じスクリプトをもう一度インポートすると、そのスクリプトのコードは再実行されず、キャッシュされたバージョンが使用されます。

具体例による説明：

introduction.py スクリプトを再利用しましょう。

# introduction.py
def my_function():
    print("Hello, World!")

my_function()

次に、同じように Article.Introduction クラスを再利用しましょう。

Class Article.Introduction Extends %RegisteredObject
{
    ClassMethod Run()
    {
        Set sys = ##class(%SYS.Python).Import("sys")
        do sys.path.append("/irisdev/app/src/python/article")
        do ##class(%SYS.Python).Import("introduction")
    }
}

今度は、同じIRISセッション内で2回続けて実行します。

iris session iris -U IRISAPP 

IRISAPP>do ##class(Article.Introduction).Run()
Hello, World!

IRISAPP>do ##class(Article.Introduction).Run()

IRISAPP>

🤯一体どういうことでしょうか？

はい、「Hello, World!」は一度だけ出力されます！

⚠️ インポートされたスクリプトはキャッシュされています。 つまり、インポートした後にスクリプトを変更しても、IRSセッションが変更されるまで変更は反映されません。

IRISで language tag を使用する場合でも同じです。

Class Article.Introduction2 Extends %RegisteredObject
{

ClassMethod Run() [ Language = python ]
{
    import os

    if not hasattr(os, 'foo'):
        os.foo = "bar"
    else:
        print("os.foo already exists:", os.foo)
}

}

実行しましょう。

iris session iris -U IRISAPP

IRISAPP>do ##class(Article.Introduction2).Run()

IRISAPP>do ##class(Article.Introduction2).Run()
os.foo already exists: bar

なんと、os モジュールはキャッシュされ、foo 属性は存在しないことに再定義されていません。

まとめ

この入門編が、IRISでPythonを使用する際に、特にスクリプトのインポートやキャッシュ処理に関して、予期しない動作が発生する理由を理解する助けになれば幸いです。

IRISでPythonを使う際のポイント：

• Pythonスクリプトで変更を確認するには、IRISセッションを毎回変更する。
  • これはバグではなく、Pythonの仕様です。
• スクリプトをインポートするとそのコードが実行されることに気を付ける。

ボーナス

待って！ スクリプトをインポートするとキャッシュされる？つじつまが合いません。 language tag = python で作業していて、スクリプトを変更したのにIRISセッションを変更しなくてもうまく動作するのは何故でしょうか？

いい質問です。これは language tag の仕組みが関係しています。language tag は実行するたびにスクリプトをもう一度読み込み、ネイティブのPythonインタープリターで新しい行を入力するかのように、行ごとに実行します。language tag はスクリプトをインポートするわけではなく、Pythonインタープリターを再起動せずに直接スクリプトを実行しているのと同じ動作をします。

例：

Class Article.Introduction2 Extends %RegisteredObject
{
ClassMethod Run() [ Language = python ]
{
    import os

    if not hasattr(os, 'foo'):
        os.foo = "bar"
    else:
        print("os.foo already exists:", os.foo)
}
}

実行しましょう。

iris session iris -U IRISAPP
IRISAPP>do ##class(Article.Introduction2).Run()

IRISAPP>do ##class(Article.Introduction2).Run()
os.foo already exists: bar  

Pythonインタープリターだと、こんな感じになります。

import os

if not hasattr(os, 'foo'):
    os.foo = "bar"
else:
    print("os.foo already exists:", os.foo)

import os
if not hasattr(os, 'foo'):
    os.foo = "bar"
else:
    print("os.foo already exists:", os.foo)

出力：

os.foo already exists: bar # only printed once

いかがでしょうか。

今後の内容 :

• Pep8
• モジュール
• ダンダーメソッド
• IRISでPythonを動かす
• ...

この記事では、マジックメソッドとしても知られるPythonダンダーメソッドについて簡単に解説します。

ダンダーメソッドとは？

ダンダーメソッドは、始めと終わりに2つのアンダースコア（__）が付いているPythonの特殊メソッドです。 このメソッドを使用することで、加算や減算、文字列表現など、組み込みの操作に対するオブジェクトの動作を定義することができます。

よくあるダンダーメソッドには、次が含まれます。

• __init__(self, ...)：オブジェクトの作成時に呼び出されます。
  • ObjectScriptの %OnNew メソッドに似ています
• __str__(self)：オブジェクトを文字列として表現するために、str() 組み込み関数と print によって呼び出されます。
• __repr__(self)：デバッグ用のオブジェクトを表現するために、repr() 組み込み関数によって呼び出されます。
• __add__(self, other)：+ 演算子が使用される際に呼び出されます。
• __len__(self)：オブジェクトの長さを返すために、len() 組み込み関数によって呼び出されます。
• __getitem__(self, key)：インデックス構文を使用してコレクションからアイテムを取得するために呼び出されます。
• __setitem__(self, key, value)：インデックス構文を使用してコレクション内にアイテムを設定するために呼び出されます。
• ... 他にもたくさんあります。

IRIS環境において、ダンダーメソッドが重要であり関連性があるのはなぜか？

Objectscriptでは、Pythonのようなシンタックスシュガーはありませんが、ダンダーメソッドを使用して同じような動作を実現できます。

例えば、インポートしたPythonモジュールにPythonのリストを返す関数があり、Objectscriptでそれを使用したいとします。 リスト内のアイテムにアクセスするには、__getitem__ ダンダーメソッドを使用する必要があります。

# src/python/article/dunder_example.py
def get_list():
    return [1, 2, 3, 4, 5]

Class Article.DunderExample Extends %RegisteredObject
{

ClassMethod Run()
{
    Set sys = ##class(%SYS.Python).Import("sys")
    do sys.path.append("/irisdev/app/src/python/article")
    set dunderExample = ##class(%SYS.Python).Import("dunder_example")
    set myList = dunderExample."get_list"()
    for i=0:1:myList."__len__"()-1 {
        write myList."__getitem__"(i), !
    }
}

}

実行しましょう。

iris session iris -U IRISAPP '##class(Article.DunderExample).Run()'

出力は以下のようになります。

1
2
3
4
5

これは、IRIS環境でPythonオブジェクトとやり取りするためにダンダーメソッドを使う方法を具体的に示しており、ObjectScript環境内で作業しながらPythonの機能を活用することができます。

ボーナス

ダンダーの優れた使い方の1つは、スクリプトがモジュールとしてインポートされた際にコードが実行されないようにするために、if __name__ == "__main__": ブロックをPythonスクリプトの最後に配置することです。

最初の記事で、スクリプトをインポートするとコードが実行されることを説明しました。 このブロックにより、スクリプトがインポートされたときではなく、直接実行されたときにのみ実行されるコードを定義できます。

例：

# src/python/article/dunder_example.py
def get_list():
    return [1, 2, 3, 4, 5]

if __name__ == "__main__":
    print(get_list())

まとめ

ダンダーメソッドを使えば、PythonのシンタックスシュガーでできることはObjectScriptでも可能です。

コミュニティの皆さんこんにちは。
 

ベクトル検索関連の処理が完全にノーマークだった私が、一先ず「やってみよう！」との事で、２つの動画のサンプルを実行してみました。
Pythonは初心者なので、アレな箇所があっても目をつぶっていただけると幸いです。

また、間違っている箇所があったら、ご指摘いただけると幸いです。

■参考にした動画

• ベクトル検索のご紹介（2024年5月30日開催　インターシステムズ開発者ウェビナー）
• IRISのベクトル検索を使ってテキストから画像を検索してみよう

■参考にしたコミュニティ記事

• Vector Search (ベクトル検索) をご紹介します

【目的】

本記事では、動画で紹介された内容を実際にIRIS環境上で実行できるよう、具体的な環境構築とコーディングを記載致します。
コミュニティの皆さんが簡単に試せるようになれば幸いです。

またGithubにサンプルソースを配置しているので、必要な方は参考にして下さい。

【準備】

■作業環境

※環境作成方法に問題のない方は、読み飛ばしていただいて構いません。

.pyファイルの中でIRISのEmbedded Pythonを動作させる際にirispythonコマンドで実行する方法はドキュメント上で紹介されていましたので、以前より使用していました。

しかし、普通のpythonコマンドを使用するとうまく実行できなかったのですが、最近その謎（原因）が解けたので紹介します。

これは、Mac特有の問題である可能性が高くWindowsやLinuxでは何の問題もなく実行できるのかもしれません。

エラーは以下のようなエラーです。

  File "/opt/iris/lib/python/iris.py", line 34, in <module>
    from pythonint import *
ImportError: IrisSecureStart failed: IRIS_ATTACH (-21)

このエラーの原因は、シェルの実行ユーザーとirisのオーナーが異なることが原因とのことです。

Macで普通にIRISをインストールするとそのオーナーはrootです。

従ってpython3コマンドを実行する時にsudoコマンドでrootになる必要があるということです。

そして以下のような環境変数の設定も必要です。

開発者の皆さん、こんにちは！

この記事では、Developer Hub にあるチュートリアルに新しいチュートリアル：InterSystems IRIS ベクトル検索を使用した RAG が追加されましたので内容をご紹介します。（準備不要でブラウザがあれば試せるチュートリアルです！）

このチュートリアルでは、生成 AI アプリケーションの精度向上に向けて、ベクトル検索と検索拡張生成（Retrieval Augmented Generation）の活用を体験できます。

具体的には、InterSystems IRIS のベクトル検索機能を活用し、生成 AI チャットボット向けのナレッジベースをサンプルコードを利用して作成します。

また、Streamlit を使用して作成したチャットボットを動かしながら、ナレッジベースの情報を追加することで生成 AI からの回答が変化していくことを確認していきます。

アカウント作成やログインも不要で  ボタンをクリックするだけで始められます👍

チュートリアルへのリンクは「開発者コミュニティのリソース」からも辿れます！

ぜひ、お試しください！​​​​​​

コミュニティの皆さん、こんにちは。
この記事では、私のアプリケーションである iris-AgenticAI をご紹介します。

エージェンティック AI の登場により、人工知能が世界とやりとりする方法に変革的な飛躍をもたらし、静的なレスポンスが動的な目標主導の問題解決にシフトしています。 OpenAI の Agentic SDK を搭載した OpenAI Agents SDK を使用すると、抽象化をほとんど行わずに軽量で使いやすいパッケージでエージェンティック AI アプリを構築できます。 これは Swarm という前回のエージェントの実験を本番対応にアップグレードしたものです。
このアプリケーションは、人間のような適応性で複雑なタスクの推論、コラボレーション、実行を行える次世代の自律 AI システムを紹介しています。

アプリケーションの機能

• エージェントループ  🔄 ツールの実行を自律的に管理し、結果を LLM に送信して、タスクが完了するまで反復処理するビルトインのループ。
• Python-First 🐍 ネイティブの Python 構文（デコレーター、ジェネレーターなど）を利用して、外部の DSL を使用せずにエージェントのオーケストレーションとチェーンを行います。
• ハンドオフ 🤝 専門化されたエージェント間でタスクを委任することで、マルチエージェントワークフローをシームレスに調整します。
• 関数ツール ⚒️ @tool で Python 関数をデコレートすることで、エージェントのツールキットに即座に統合させます。
• ベクトル検索（RAG） 🧠 RAG 検索のためのベクトルストアのネイティブ統合。
• トレース 🔍 リアルタイムでエージェントワークフローの可視化、デバッグ、監視を行うためのビルトインのトレース機能（LangSmith の代替サービスとして考えられます）。
• MCP サーバー 🌐 stdio と HTTP によるモデルコンテキストプロトコル（MCP）で、クロスプロセスエージェント通信を可能にします。
• Chainlit UI 🖥️ 最小限のコードで対話型チャットインターフェースを構築するための統合 Chainlit フレームワーク。
• ステートフルメモリ 🧠 継続性を実現し、長時間実行するタスクに対応するために、セッション間でチャット履歴、コンテキスト、およびエージェントの状態を保持します。

エージェント

エージェントは、アプリの主要な構成要素です。 エージェントは大規模言語モデル（LLM）で、instructions と tools で構成されています。 基本的な構成 以下は、構成されるエージェントの最も一般的なプロパティです。

Instructions: 開発者メッセージまたはシステムプロンプトとも呼ば出る指示。
model: LLM が使用するモデル。オプションとして model_settings を使用して、temperature や top_p など、モデルのチューニングパラメーターを構成できます。
tools: タスクを達成するためにエージェントが使用できるツール。

from agents import Agent, ModelSettings, function_tool

@function_tooldefget_weather(city: str) -> str:returnf"The weather in {city} is sunny"
agent = Agent(
    name="Haiku agent",
    instructions="Always respond in haiku form",
    model="o3-mini",
    tools=[get_weather],
)

エージェントの実行

Runner クラスを使ってエージェントを実行できます。 これには 3 つのオプションがあります。

1. Runner.run(): 非同期で実行し、RunResult を返します。
2. Runner.run_sync(): 非同期メソッドで、内部で .run() を実行します。
3. Runner.run_streamed(): 非同期で実行し、RunResultStreaming を返します。 ストリーミングモードで LLM を呼び出し、イベントを受け取るたびにユーザーにストリーミングします。

from agents import Agent, Runner
asyncdefmain():
agent = Agent(name="Assistant", instructions="You are a helpful assistant")
result = <span class="hljs-keyword">await</span> Runner.run(agent, <span class="hljs-string">"Write a haiku about recursion in programming."</span>)
print(result.final_output)
<span class="hljs-comment"># Code within the code,</span>
<span class="hljs-comment"># Functions calling themselves,</span>
<span class="hljs-comment"># Infinite loop's dance.</span></code></pre>

エージェントアーキテクチャ
アプリケーションは 7 つの専門化されたエージェントで構成されています。
Triage エージェント 🤖
機能: ユーザー入力を受け取り、ハンドオフでタスクを委任する主要ルーター
例: 「Show production errors（プロダクションエラーを表示）」は IRIS プロダクションエージェントに転送されます。
ベクトル検索エージェント 🤖
機能: IRIS 2025.1 リリースノートの内容を提供します（RAG 機能）
例: 「Provide me summary of Release Notes（リリースノートの要約を提供）」はベクトル検索エージェントに転送されます。
IRIS Dashboard エージェント 🤖
機能: リアルタイムの管理ポータルメトリクスを提供します: plaintext Copy
ApplicationErrors, CSPSessions, CacheEfficiency, DatabaseSpace, DiskReads,  
DiskWrites, ECPAppServer, ECPDataServer, GloRefs, JournalStatus,  
LicenseCurrent, LockTable, Processes, SystemUpTime, WriteDaemon, [...]
IRIS 実行プロセスエージェント 🤖
機能: アクティブなプロセスを次の詳細とともに監視します。
Process ID | Namespace | Routine | State | PidExternal
IRIS Production エージェント 🤖
機能: プロダクションの開始と停止の機能とともにプロダクションの詳細を提供します。
WebSearch エージェント 🤖
機能: API 統合によりコンテキストウェブ検索を実行します。
Order エージェント 🤖
機能: 注文 ID を使用して注文のステータスを取得します。

ハンドオフ
ハンドオフによって、タスクを別のエージェントに委任することができます。 これは特に、それぞれのエージェントが異なる分野に特化している場合に役立ちます。 たとえば、カスタマーサポートアプリには、注文ステータス、返金、FAQ などのそれぞれのタスクを専門的に処理するエージェントが実装されている場合があります。
Triage エージェントはこのアプリケーションのメインエージェントで、ユーザー入力に基づいて別のエージェントにタスクを委任するエージェントです。
#TRIAGE AGENT, Main agent receives user input and delegates to other agent by using handoffs
    triage_agent = Agent(
        name="Triage agent",
        instructions=(
            "Handoff to appropriate agent based on user query.""if they ask about Release Notes, handoff to the vector_search_agent.""If they ask about production, handoff to the production agent.""If they ask about dashboard, handoff to the dashboard agent.""If they ask about process, handoff to the processes agent.""use the WebSearchAgent tool to find information related to the user's query and do not use this agent is query is about Release Notes.""If they ask about order, handoff to the order_agent."
        ),
        handoffs=[vector_search_agent,production_agent,dashboard_agent,processes_agent,order_agent,web_search_agent]
    )

トレース
Agents SDK には、トレース機能が組み込まれており、エージェントの実行中にLLM の生成、ツールの呼び出し、ハンドオフ、ガードレール、カスタムイベントの発生など、イベントの包括的な記録を収集できます。 Traces ダッシュボードを使用すると、開発中と本番稼動時にワークフローのデバッグ、可視化、監視を行えます。
https://platform.openai.com/logs
 

アプリケーションのインターフェース
アプリケーションのワークフロープロセス
ベクトル検索エージェント
ベクトル検索エージェントは、「New in InterSystems IRIS 2025.1」のテキスト情報のデータがまだ存在しない場合に、そのデータを一度だけ自動的に IRIS Vector Store に取り込みます。  

以下のクエリを使用してデータを検索しましょう
SELECTid, embedding, document, metadata
FROM SQLUser.AgenticAIRAG
Triage エージェントはユーザー入力を受け取って、質問をベクトル検索エージェントに転送します。
IRIS Dashboard エージェント
Triage エージェントはユーザー入力を受け取って、質問を IRIS Dashboard エージェントに転送します。

IRIS Processes エージェント
Triage エージェントはユーザー入力を受け取って、質問を IRIS Processes エージェントに転送します。

IRIS Production エージェント
Production エージェントを使用して、プロダクションの開始と停止を行います。

Production エージェントを使用して、プロダクションの詳細を取得します。
Local エージェント
Triage エLocal ージェントはユーザー入力を受け取って、質問を Local Order エージェントに転送します。

WebSearch エージェント
ここでは、Triage エージェントは 2 つの質問を受け取って、WebSearch エージェントに転送します。
MCP Server アプリケーション
MCP Server は https://localhost:8000/sse で実行しています。

以下のコードで MCP Server を起動しています。
import os
import shutil
import subprocess
import time
from typing import Any
from dotenv import load_dotenv
load_dotenv()
#Get OPENAI Key, if not fond in .env then get the GEIMINI API KEY#IF Both defined then take OPENAI Key 
openai_api_key = os.getenv("OPENAI_API_KEY")
ifnot openai_api_key:
raise ValueError("OPENAI_API_KEY is not set. Please ensure to defined in .env file.")
ifname == "main":
# Let's make sure the user has uv installedifnot shutil.which("uv"):
raise RuntimeError(
"uv is not installed. Please install it: https://docs.astral.sh/uv/getting-started/installation/"
)
<span class="hljs-comment"># We'll run the SSE server in a subprocess. Usually this would be a remote server, but for this</span>
<span class="hljs-comment"># demo, we'll run it locally at http://localhost:8000/sse</span>
process: subprocess.Popen[Any] | <span class="hljs-keyword">None</span> = <span class="hljs-keyword">None</span>
<span class="hljs-keyword">try</span>:
    this_dir = os.path.dirname(os.path.abspath(__file__))
    server_file = os.path.join(this_dir, <span class="hljs-string">"MCPserver.py"</span>)

    print(<span class="hljs-string">"Starting SSE server at http://localhost:8000/sse ..."</span>)

    <span class="hljs-comment"># Run `uv run server.py` to start the SSE server</span>
    process = subprocess.Popen([<span class="hljs-string">"uv"</span>, <span class="hljs-string">"run"</span>, server_file])
    <span class="hljs-comment"># Give it 3 seconds to start</span>
    time.sleep(<span class="hljs-number">3</span>)

    print(<span class="hljs-string">"SSE server started. Running example...\n\n"</span>)
<span class="hljs-keyword">except</span> Exception <span class="hljs-keyword">as</span> e:
    print(<span class="hljs-string">f"Error starting SSE server: <span class="hljs-subst">{e}</span>"</span>)
    exit(<span class="hljs-number">1</span>)
 
MCP Server には次のツールが備わっています。
IRIS 2025.1 リリースノートの詳細を提供（ベクトル検索）
IRIS 情報ツール
天気チェックツール
シークレットワードの検索ツール（ローカル関数）
加算ツール（ローカル関数）
MCP アプリケーションは  http://localhost:8001で実行しています。

 
MCP Server ベクトル検索（RAG）機能
MCP Server には InterSystems IRIS ベクトル検索インジェスト機能と検索拡張生成（RAG）機能が備わっています。

MCP Server の他の機能
MCP Server は、ユーザー入力に基づいて、適切なツールに動的にタスクを委任します。

詳細については、iris-AgenticAI の Open Exchange アプリケーションページをご覧ください。
以上です

開発者の皆さん、こんにちは！

Windows 版 IRIS／IRIS for Health 2025.1 以降で Embedded Python をご利用いただく場合、Windows に Python のインストールが必要になりました。

以前のバージョンから Embedded Python をご利用いただいている場合は、新しいバージョンにアップグレードした後、Python のインストールと IRIS 側に必要な設定がありますのでご注意ください。

※ 2024.1 以前のバージョンでは、IRIS インストールと同時にインストールされる Python ご利用いただく必要があったため、Windows への Python インストールは不要でした。

補足：フレキシブル Python ランタイム機能の導入により、OS にインストールされた Python のバージョンを IRIS 側で指定できるようになりました。

詳細はドキュメントもご参照ください：フレキシブル Python ランタイム機能の概要

Embedded Python 利用までの手順は以下の通りです。

1) サポートする Python のバージョンを確認

サポートしている Python のバージョンを確認します。（Windows は、Python 3.9以降）

これは InterSystems FAQ サイトの記事です。

InterSystems 製品では、ファイルオープン時に文字コードを指定すれば指定の文字コードで正しくファイルの中身を処理できます。

文字コードを指定しない場合、InterSystems 製品をインストールした OS に合わせて設定されたファイル I/O 用文字コードを利用してファイルをオープンします（Linux 系は UTF8、Windows は SJIS）。

また、文字列については文字コードが判明していれば $ZCONVERT() 関数を使用して指定文字コードで文字列を処理することができます。

　例）$ZCONVERT(文字列,"I","IRIS内文字コード")

文字コードが不明な場合、残念ながら InterSystems 製品だけでそのコードを判別することができないため、例えば Embedded Python で Python の chardet パッケージを使用して文字コード判別し、IRIS 内文字コードを取得しファイルオープン、文字列の文字コード変換をすることができます。

chardetパッケージについては、外部サイトですが参考となります。ぜひご参照ください。

参考ページ：［解決！Python］テキストファイルのエンコーディングを調べて、その内容を読み込むには（chardetパッケージ）

次回の Python コンテストでは、Python を使用して IRIS をデータベースとして使用する簡単な REST アプリケーションを作成する方法についての小さなデモを作成しようと思います。 以下のツールを使用します。

• FastAPI フレームワーク: 高パフォーマンス、学習しやすい、高速コーディング、プロダクション対応
• SQLAlchemy: Python SQL ツールキットで、アプリケーション開発者が SQL の全性能と柔軟性を活用できるオブジェクトリレーションマッパーです。
• Alembic: Python 用の SQLAlchemy データベースツールキットと使用する軽量のデータベース移行ツール。
• Uvicorn: Python の ASGI ウェブサーバー実装。

環境の準備

バージョン 3.7 以降の Python がすでにインストール済みだと思います。 プロジェクトフォルダを作成し、その中に以下のコンテンツで requirements.txt ファイルを作成します。

fastapi==0.101.1
alembic==1.11.1
uvicorn==0.22.0
sqlalchemy==2.0.20
sqlalchemy-iris==0.10.5

Python で仮想環境を使用することをお勧めします。新しい環境を作成して有効化しましょう。

python -m venv env && source env/bin/activate

そして、依存関係をインストールします。

pip install -r requirements.txt

クイックスタート

FastAPI を使って最も単純な REST Api を作成しましょう。 これを行うには、app/main.py を作成します。

from fastapi import FastAPI
app = FastAPI(
title='TODO Application',
version='1.0.0',
)
@app.get("/ping")asyncdefpong():return {"ping": "pong!"}

この時点で、アプリケーションを純分に起動して動作させることができます。 サーバーの起動には、uvicorn を使用します。

$ uvicorn app.main:app         
INFO:     Started server process [94936]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

ping リクエストを発行できます。

$ curl http://localhost:8000/ping
{"ping":"pong!"}

FastAPI には API をテストできる UI が用意されています。

Docker 化環境

IRIS をアプリケーションに追加するには、コンテナーを使用します。 IRIS イメージはそのままで使用できますが、Python アプリケーション用の Docker イメージを作成する必要があります。 また、Dockerfile が必要です。

FROM python:3.11-slim-buster
WORKDIR /usr/src/app
RUN --mount=type=bind,src=.,dst=. 

pip install --upgrade pip && 

pip install -r requirements.txt
COPY . .
ENTRYPOINT [ "/usr/src/app/entrypoint.sh" ]

コンテナー内でアプリケーションを起動するには、簡単な entrypoint.sh が必要です。

#!/bin/sh
# Run SQL Migrations, to make DB Schema up to date
alembic upgrade head
# Start Python application
uvicorn app.main:app 

--workers 1 

--host 0.0.0.0 

--port 8000 "$@"

実行フラグを忘れずに追加しましょう。

chmod +x entrypoint.sh

docker-compose.yml で IRIS と組み合わせます。

version:"3"services:  iris:    image:intersystemsdc/iris-community    ports:      -1972    environment:      -IRISUSERNAME=demo      -IRISPASSWORD=demo    healthcheck:      test:/irisHealth.sh      interval:5s  app:    build:.    ports:      -8000:8000    environment:      -DATABASE_URL=iris://demo:demo@iris:1972/USER    volumes:      -./:/usr/src/app    depends_on:      iris:        condition:service_healthy    command:      ---reload

ではビルドしましょう。

docker-compose build

最初のデータモデル

アプリケーションに IRIS データベースへのアクセスを宣言し、app/db.py ファイルを追加しましょう。このファイルによって データベースにアクセスできるように SQLAlchemy が構成されます。これは docker-compose.yml によって渡される URL で定義されます。これには後でアプリで使用するハンドラーがいくつか含まれています。

import os
from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import DeclarativeMeta, declarative_base
from sqlalchemy.orm import sessionmaker
DATABASE_URL = os.environ.get("DATABASE_URL")
ifnot DATABASE_URL:
DATABASE_URL = "iris://demo:demo@localhost:1972/USER"
engine = create_engine(DATABASE_URL, echo=True, future=True)
Base: DeclarativeMeta = declarative_base()
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
definit_db():
engine.connect()
defget_session():
session = SessionLocal()
yield session

では、初の唯一のモデルをアプリケーションに定義しましょう。 ファイル app/models.py を作成して編集します。SQLAlchemy を使用して、Todo と言う、id、title、description の 3 つ列を持つモデルを定義します。

from sqlalchemy import Column, Integer, String, Text
from app.db import Base
classTodo(Base):tablename = 'todo'
id = Column(Integer, primary_key=True, index=True)
title = Column(String(200), index=True, nullable=False)
description = Column(Text, nullable=False)

SQL の移行の準備

変化し続ける世界では、アプリケーションは将来的に改善されると考えるため、テーブル構造は最終的なものではなく、さらにテーブル、列、インデックスなどを追加できるとわかっています。 この場合の最善のシナリオは、SQL Migration ツールを使用することです。これは、アプリケーションのバージョンに応じてデータベースの現在の構造をアップグレードできるツールであり、何かが誤ってしまった場合には、これらのツールを使用することでダウングレードすることもできます。 このプロジェクトでは Python と SQLAlchemy を使用していますが、SQLAlchemy の作者は Alembic というツールを提供しており、ここではそれを使用します。

IRIS と、アプリケーションを含むコンテナーを起動する必要がありますが、この時点では、コマンドを実行できるように Bash する必要があります。

$ docker-compose run --entrypoint bash app
[+] Creating 2/0
 ✔ Network fastapi-iris-demo_default   Created                                                                                                                                                        0.0s 
 ✔ Container fastapi-iris-demo-iris-1  Created                                                                                                                                                        0.0s 
[+] Running 1/1
 ✔ Container fastapi-iris-demo-iris-1  Started                                                                                                                                                        0.1s 
root@7bf903cd2721:/usr/src/app# 

コマンド alembic init app/migrations を実行します。

root@7bf903cd2721:/usr/src/app# alembic init app/migrations
  Creating directory '/usr/src/app/app/migrations' ...  done
  Creating directory '/usr/src/app/app/migrations/versions' ...  done
  Generating /usr/src/app/app/migrations/README ...  done
  Generating /usr/src/app/app/migrations/script.py.mako ...  done
  Generating /usr/src/app/app/migrations/env.py ...  done
  Generating /usr/src/app/alembic.ini ...  done
  Please edit configuration/connection/logging settings in '/usr/src/app/alembic.ini' before proceeding.
root@7bf903cd2721:/usr/src/app#

これにより Alembic 構成が準備されたため、アプリケーションのニーズに適合するように修正する必要があります。 これを行うには app/migrations/env.py ファイルを編集します。 これはファイルの始まりに過ぎないため、更新する必要があります。sqlalchemy.url と target_metadata を更新することに専念しましょう。 その以下の変更はありません。

import os
import urllib.parse
from logging.config import fileConfig
from sqlalchemy import engine_from_config
from sqlalchemy import pool
from alembic import context
# this is the Alembic Config object, which provides# access to the values within the .ini file in use.
config = context.config
DATABASE_URL = os.environ.get("DATABASE_URL")
decoded_uri = urllib.parse.unquote(DATABASE_URL)
config.set_main_option("sqlalchemy.url", decoded_uri)
# Interpret the config file for Python logging.# This line sets up loggers basically.if config.config_file_name isnotNone:
fileConfig(config.config_file_name)
# add your model's MetaData object here# for 'autogenerate' supportfrom app.models import Base
target_metadata = Base.metadata
# target_metadata = None

すでにモデルが存在するため、コマンド alembic revision --autogenerate で移行を作成する必要があります。

root@7bf903cd2721:/usr/src/app# alembic revision --autogenerate
INFO  [alembic.runtime.migration] Context impl IRISImpl.
INFO  [alembic.runtime.migration] Will assume non-transactional DDL.
INFO  [alembic.autogenerate.compare] Detected added table 'todo'
INFO  [alembic.autogenerate.compare] Detected added index 'ix_todo_id' on '['id']'
INFO  [alembic.autogenerate.compare] Detected added index 'ix_todo_title' on '['title']'
  Generating /usr/src/app/app/migrations/versions/1e4d3b4d51ca_.py ...  done
root@7bf903cd2721:/usr/src/app# 

"""empty message
Revision ID: 1e4d3b4d51ca
Revises:
Create Date: 2023-08-22 07:08:01.586330
"""from alembic import op
import sqlalchemy as sa
# revision identifiers, used by Alembic.
revision = '1e4d3b4d51ca'
down_revision = None
branch_labels = None
depends_on = Nonedefupgrade() -> None:# ### commands auto generated by Alembic - please adjust! ###
op.create_table('todo',
sa.Column('id', sa.Integer(), nullable=False),
sa.Column('title', sa.String(length=200), nullable=False),
sa.Column('description', sa.Text(), nullable=False),
sa.PrimaryKeyConstraint('id')
)
op.create_index(op.f('ix_todo_id'), 'todo', ['id'], unique=False)
op.create_index(op.f('ix_todo_title'), 'todo', ['title'], unique=False)
# ### end Alembic commands ###defdowngrade() -> None:# ### commands auto generated by Alembic - please adjust! ###
op.drop_index(op.f('ix_todo_title'), table_name='todo')
op.drop_index(op.f('ix_todo_id'), table_name='todo')
op.drop_table('todo')
# ### end Alembic commands ###

では、これをデータベースに適用しましょう。コマンド alembic upgrade head を使用します。ここで、head は最新バージョンにアップグレードするためのキーワードです。

root@7bf903cd2721:/usr/src/app# alembic upgrade head
INFO  [alembic.runtime.migration] Context impl IRISImpl.
INFO  [alembic.runtime.migration] Will assume non-transactional DDL.
INFO  [alembic.runtime.migration] Running upgrade  -> 1e4d3b4d51ca, empty message

root@7bf903cd2721:/usr/src/app# alembic downgrade head-1
INFO  [alembic.runtime.migration] Context impl IRISImpl.
INFO  [alembic.runtime.migration] Will assume non-transactional DDL.
INFO  [alembic.runtime.migration] Running downgrade 1e4d3b4d51ca -> , empty message

現在の状態をいつでも確認できます。いくつかの移行が欠落している場合にはその情報を得られます。

root@7bf903cd2721:/usr/src/app# alembic check
INFO  [alembic.runtime.migration] Context impl IRISImpl.
INFO  [alembic.runtime.migration] Will assume non-transactional DDL.
No new upgrade operations detected.

データをアクセス可能にする

REST に戻り、実行させる必要があります。現在のコンテナーを終了し、アプリサービスを通常どおり実行すると、uvicorn には --reload フラグが設定されているため、Python ファイル内の変更をチェックし、変更がある場合には再起動されます。

$ docker-compose up app
[+] Running 2/0
 ✔ Container fastapi-iris-demo-iris-1  Running                                                                                                                                                        0.0s 
 ✔ Container fastapi-iris-demo-app-1   Created                                                                                                                                                        0.0s 
Attaching to fastapi-iris-demo-app-1, fastapi-iris-demo-iris-1
fastapi-iris-demo-app-1   | INFO  [alembic.runtime.migration] Context impl IRISImpl.
fastapi-iris-demo-app-1   | INFO  [alembic.runtime.migration] Will assume non-transactional DDL.
fastapi-iris-demo-app-1   | INFO:     Will watch for changes in these directories: ['/usr/src/app']
fastapi-iris-demo-app-1   | INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
fastapi-iris-demo-app-1   | INFO:     Started reloader process [8] using StatReload
fastapi-iris-demo-app-1   | INFO:     Started server process [10]
fastapi-iris-demo-app-1   | INFO:     Waiting for application startup.
fastapi-iris-demo-app-1   | INFO:     Application startup complete.

FastAPI は Pydantic プロジェクトを使用してデータスキーマを宣言しているため、それも必要です。app/schemas.py を作成しましょう。列は models.py と同じですが、単純な Python フォームを使用します。

from pydantic import BaseModel
classTodoCreate(BaseModel):
title: str
description: str
classTodo(TodoCreate):
id: int
<span class="hljs-class"><span class="hljs-keyword">class</span> <span class="hljs-title">Config</span>:</span>
    from_attributes = <span class="hljs-keyword">True</span>

SQLAlchemy ORM を使ってデータベースを操作する app/crud.py で CRUD 操作を宣言します。

from sqlalchemy.orm import Session
from . import models, schemas
defget_todos(db: Session, skip: int = 0, limit: int = 100):return db.query(models.Todo).offset(skip).limit(limit).all()
defcreate_todo(db: Session, todo: schemas.TodoCreate):
db_todo = models.Todo(**todo.dict())
db.add(db_todo)
db.commit()
db.refresh(db_todo)
return db_todo

そして最後に、app/main.py を更新し、ToDo を読み取って作成するルートを追加できます。

from fastapi import FastAPI, Depends
from .db import init_db, get_session
from . import crud, schemas
app = FastAPI(
title='TODO Application',
version='1.0.0',
)
@app.on_event("startup")defon_startup():
init_db()
@app.get("/ping")asyncdefpong():return {"ping": "pong!"}
@app.get("/todo", response_model=list[schemas.Todo])asyncdefread_todos(skip: int = 0, limit: int = 100, session=Depends(get_session)):
todos = crud.get_todos(session, skip=skip, limit=limit)
return todos
@app.post("/todo", response_model=schemas.Todo)asyncdefcreate_todo(todo: schemas.TodoCreate, session=Depends(get_session)):return crud.create_todo(db=session, todo=todo)

これに応じてドキュメント ページが更新され、実際に操作できるようになりました。

IRIS で確認してみましょう。

─$ docker-compose exec iris irissqlcli iris+emb:///
Server:  IRIS for UNIX (Ubuntu Server LTS for ARM64 Containers) 2023.2 (Build 227U) Mon Jul 31 2023 17:43:25 EDT
Version: 0.5.4
[SQL]irisowner@/usr/irissys/:USER> .tables
+-------------------------+
| TABLE_NAME              |
+-------------------------+
| SQLUser.alembic_version |
| SQLUser.todo            |
+-------------------------+
Time: 0.043s
[SQL]irisowner@/usr/irissys/:USER> select * from todo
+----+-------+---------------------+
| id | title | description         |
+----+-------+---------------------+
| 1  | demo  | it's really working |
+----+-------+---------------------+
1 row in set
Time: 0.004s
[SQL]irisowner@/usr/irissys/:USER> select * from alembic_version
+--------------+
| version_num  |
+--------------+
| 1e4d3b4d51ca |
+--------------+
1 row in set
Time: 0.045s
[SQL]irisowner@/usr/irissys/:USER>

REST の作成において Python と FastAPI を簡単に使用していただけたなら幸いです。 このプロジェクトのソースコードは、GitHub の https://github.com/caretdev/fastapi-iris-demo にあります。

Django フレームワークは長年学習したいと思ってきましたが、いつも他の差し迫ったプロジェクトが優先されてきました。 多くの開発者と同様に、機械学習においては Python を使用していますが、初めてウェブプログラミングについて学習したころは、PHP がまだまだ優勢でした。そのため、機械学習の作品を公開する目的でウェブアプリケーションを作成するための新しい複雑なフレームワークを選択する機会が訪れても、私は依然として PHP に目を向けていました。 ウェブサイトの構築には Laravel と呼ばれるフレームワークを使用してきましたが、この PHP フレームワークから最新の MVC（モデルビューコントローラー）というウェブプログラミングのパターンに出会いました。 さらに複雑なことに、私は最新の JavaScript フレームワークを使用してフロントエンドを構築するのを好んでいます。 React を使用するのがより一般的のようですが、私は Vue.js に一番慣れているため、このプロジェクトではそれを使用することにしました。

なぜ複雑なフレームワークを使用するのでしょうか？ Django、Laravel、React、または Vue などのフレームワークを学習する際の最大の難関は何でしょうか？

答えは人それぞれですが、私は MVC フレームワークがアプリの構造化に関するガイドを非常に多く提供してくれるため、気に入っています。毎回、作り直す必要がありません。 初めはこういったフレームワークは制約が多くて難解に思えるかもしれませんが、構造に慣れてしまえば、新しい機能をより追加しやすいと思います。

問題は、物事があまりにも単純になりすぎる可能性があることです。 Django のようなフレームワークは、よく知られた概念に基づいているかもしれませんが、Django では特に馴染みのない名前と構造を持つ多くの省略形や仮定に依存しています。 私のアプリケーションでは、Django は API とすべてのウェブルーティングを処理しています。 新しい API エンドポイントを追加する場合は、views.py のファイルに関数を追加してから、urls.py ファイルに移動して、その関数をインポートするステートメントと、API エンドポイントが提供されている URL を定義する別のステートメントを追加する必要があります。 その後で、データを取得してユーザーに表示するか操作するために、そのエンドポイントをクエリする JavaScript を使って、フロントエンドの Vue コンポーネントを編集する必要があります。

プロジェクトのセットアップが完了したら、このような機能の追加は迅速に行えます。 約 4 行のコードを追加するだけで、HTTP リクエストを処理し、必要なデータを JSON 形式で返すように、views.py ファイルの新しい関数に必要なロジックに集中できます。 難しいのは、それらのファイルが何であるか、そしてそれらがどのように連携してアプリケーション全体を作り上げるかを学ぶことです。

Django のようなフレームワークを学習するには、実際に動作する例を探して、データのフローを感じ取れる小さな変更を適用して見るのが最適な方法だと思います。 概念が明確になり始めて理解できるようになってきたら、ドキュメントを参考にしましょう。 AI モデルにコードを説明してもらい、様々な標準ファイルがフレームワークでどのように動作するかを尋ねましょう。 これらのツールが、長期的には時間を節約し、アプリケーションの保守と更新を容易にする方法として登場したことにすぐに気づくでしょう。 Django と Vue フレームワークには標準の構造があるため、後で戻ってきても、なぜ特定の方法でコーディングしたのかをすぐに理解でき、作業についての理解を再び深めやすくなっているでしょう。 また、アプリケーションの基本構造に慣れているため、他の人のアプリケーションを理解し、主な機能を把握するのもより簡単です。

では、これから始めようとしている人の支援となる Django の基礎とは何でしょうか？ 私にとっては、最初に理解すべきことは、Django プロジェクトは Django の新規プロジェクトを作成するコマンドの実行によって 生成され、これによって構築を開始するために使用できる「基本プロジェクト」を構成する一連の基本ファイルとフォルダが生成されるということです。 プロジェクトフォルダには、プロジェクト全体に適用される設定を含むいくつかの Python ファイルがあります。 頻繫にアクセスする重要なフォルダは、すべての設定が含まれる settings.py と、urls.py です。 「Django はどのようにして静的ファイルを配置する場所を決定しているのか」といった疑問がある場合、その答えは通常 settings.py のどこかにあります。 アプリケーションに新しい URL を追加する場合は、urls.py ファイルを更新する必要があります。

これらのプロジェクトレベルのファイルと共に、プロジェクト内のアプリごとにフォルダを作成します。 これらのアプリは登録されている必要があります。つまり、 settings.py ファイルで名前を付ける必要があります。 プロジェクト内のメインのアプリフォルダはドキュメントと呼ばれます。 どのフォルダ内には、models.py ファイル、serializer.py ファイル、views.py ファイルがあります。 ファイルは他にもありますが、これらが重要な 3 つのファイルです。

models.py 内には、Document オブジェクトとそのフィールドを指定します。 Document オブジェクトに保管する予定の情報を保存するために必要なスキーマを使って IRIS データベースに Documents テーブルを作成するのは、Django に任せられます。 私の models.py ファイルでは、Documents には 255 文字以内の名前、大量のテキストであるコンテンツフィールド、ベクトルが補完されるデータベース名（別のテキストフィールド）、埋め込みタイプ（別のテキストフィールド）、および数値で表現されるベクトル埋め込みの次元が含まれることを指定しています。 これらの定義を使用することで、Fjango は必要な列タイプで必要なデータベーステーブルを作成します。 すると、データベースへのオブジェクトの保存は、Document.save() だけで完了です。

serializer.py ファイル内には、オブジェクトと JSON の変換方法に関する定義が含まれます。 基本的なユースケースでは、これを定義する標準的な方法があり、このプロジェクトで確認できます。

では、Django の核心である views.py ファイルを確認しましょう。 ここに、HTTP リクエストを受け取って、HTTP レスポンス全体、または JSON API の場合は JSON API レスポンスなどのデータを返す関数を定義します。 つまり、Django ではウェブページ全体を制作して、アプリのフロントエンドとしても使用することも、JSON データのみを提供して、フロントエンドを全く別のプラットフォームで構築することもできます。

最初は、一見恣意的なファイルや規則をすべて使用するのは面倒に感じるかもしれませんが、そうすることでアプリケーションが動作し始め、HTTP リクエストを処理して、レスポンスとして正しいデータを提供するようになることが分かれば、新しい機能を構築し続けるのが非常に楽しくなります。 HTTP リクエストを処理するオブジェクト、ウェブルート、および関数を 1 つ定義すれば、2 つ目、そして 3 つ目を簡単に定義してアプリケーションに機能を追加できるようになります。

私のプロジェクトは、github: https://github.com/grongierisc/iris-django-template にある @Guillaume Rongier が作成した Iris Django Template をフォークしたものです。

このテンプレートには Django のみが含まれており、Django フレームワークの学習に非常に役立ちました。私が行った主な追加項目の 1 つは、Tailwind CSS を使用した Vue.js の追加です。最新の JavaScript フレームワークをこのパッケージに統合して、IRIS で実行する単一ページのアプリケーションを作成できます。 単一ページのアプリケーションは、xhr リクエストを送信して JSON データを取得し、完全に再読み込みすることなく動的にページを更新する JavaScript アプリケーションです。 これには長所と短所がありますが、最新のウェブ開発の特徴です。

RAG と IRIS 上のベクトルストアの例としてだけでなく、Vue.js と Tailwind を使って IRIS 上に最新の柔軟なウェブアプリケーションを簡単に素早く作成する目的で Django を使用するためのテンプレートとして、私のプロジェクトを確認することをお勧めします。 リポジトリはこちらの GitHub にあります: https://github.com/mindfulcoder49/iris-django-template

ご質問があれば、ぜひお答えします。このプロジェクトを独自のユースケースに適合しようとするする際に問題が発生した場合は、私の洞察を提供いたします。

これは、InterSystems FAQサイトの記事です。

メソッドの実装に使用する言語を明示する場合は、下記のようにメソッドキーワードで「Language＝～～～」と指定します。

Method name(formal_spec) As returnclass [ Language = language ]
{    //implementation }

 指定できるLanguageの値は下記のとおりです。

• objectscript (既定) — ObjectScript
• python — 組み込み Python
• tsql — Transact-SQL
• ispl — Informix ストアド・プロシージャ言語

ドキュメント：Language (メソッド・キーワード)

上記の通り、ObjectScriptで記載する場合は、「Language＝objectscript」と指定します。
但し、CSP内の<SCRIPT>タグ内で指定する場合は、下記の通り、「LANGUAGE＝’cache’」と指定することにご注意ください。

<SCRIPT LANGUAGE='cache',　～～～>

ドキュメント：<SCRIPT>  

※CSPページは、IRISでは非推奨の機能です。

説明

これは、ネイティブウェブアプリケーションとして IRIS にデプロイできる Django アプリケーションのテンプレートです。

インストール

1. リポジトリをクローンする
2. 仮想環境を作成する
3. 要件をインストールする
4. docker-compose ファイルを実行する

git clone
cd iris-django-template
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
docker-compose up

使用法

ベース URL は http://localhost:53795/django/ です。

エンドポイント

• /iris - IRISAPP ネームスペースに存在する上位 10 個のクラスを持つ JSON オブジェクトを返します。
• /interop - IRIS の相互運用性フレームワークをテストするための ping エンドポイント。
• /api/posts - Post オブジェクトの単純な CRUD エンドポイント。
• ``/api/comments` - Comment オブジェクトの単純な CRUD エンドポイント。

このテンプレートからの開発方法

WSGI 導入記事をご覧ください: wsgi-introduction。

概要: セキュリティポータルで DEBUG フラグをトグルすると、開発作業の過程で変更内容がアプリケーションに反映されるようになります。

コードの説明

Django アプリケーションは次のように構造化されています。

• app - Django プロジェクトフォルダ
  • app - 構成用の Django アプリフォルダ
    • settings.py - Django の設定ファイル
    • urls.py - ビューを URL に接続する Django URL 構成ファイル
    • wsgi.py - Django WSGI ファイル
    • asgi.py - Django ASGI ファイル
  • community - コミュニティアプリの Django アプリフォルダ、Post と Comment オブジェクトでの CRUD 操作
    • models.py - Post と Comment オブジェクトの Django モデルファイル
    • views.py - Post と Comment オブジェクトにアクセスするための Django ビューファイル
    • serializers.py - Post と Comment オブジェクトの Django シリアライザーファイル
    • admin.py - 管理インターフェースに CRUD 操作を追加する Django 管理ファイル
    • migrations - データベースを構築するための Django マイグレーションフォルダ
    • fixtures - Django fixtures フォルダデモデータ
  • sqloniris - IRIS アプリでの SQL に使用する Django アプリフォルダ
    • views.py - IRISAPP ネームスペースをクエリするための Django ビューファイル
    • apps.py - Django アプリ構成ファイル
  • interop - 相互運用性アプリ用の Django アプリフォルダ
    • views.py - 相互運用性フレームワークをテストするための Django ビューファイル
    • apps.py - Django アプリ構成ファイル
  • manage.py - Django 管理ファイル

app/settings.py

このファイルには、アプリケーションの Django 設定が含まれます。

...

# Application definition

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'community',
    'sqloniris',
    'interop',
    'rest_framework'
]

...

REST_FRAMEWORK = {
    # Use Django's standard `django.contrib.auth` permissions,
    # or allow read-only access for unauthenticated users.
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly'
    ],
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination',
    'PAGE_SIZE': 20
}

...

DATABASES = {
    "default": {
        "ENGINE": "django_iris",
        "EMBEDDED": True,
        "NAMESPACE": "IRISAPP",
        "USER":"SuperUser",
        "PASSWORD":"SYS",
    }
}

一部の重要な設定:

• INSTALLED_APPS - Django プロジェクトにインストール済みのアプリのリストが含まれます。
  • community - Post と Comment オブジェクトでの CRUD 操作用 Django アプリ。
  • sqloniris - IRIS での SQL 操作に使用する Django アプリ。
  • interop - 相互運用性操作用の Django アプリ。
  • rest_framework - REST API 用の Django REST フレームワーク。
• REST_FRAMEWORK - Django REST フレームワークの設定が含まれます。
  • DEFAULT_PERMISSION_CLASSES - 認証済みのユーザーのみが CRUD 操作を実行できます。
  • DEFAULT_PAGINATION_CLASS - REST API のページネーションクラス。
• DATABASES - IRIS データベース接続の設定が含まれます。
  • ここでは、django_iris エンジンを使って IRIS データベースに接続しています。

app/urls.py

このファイルには、Django アプリケーションの URL 構成が含まれます。

from django.contrib import admin
from django.urls import path,include
from rest_framework import routers
from community.views import PostViewSet, CommentViewSet
from sqloniris.views import index
from interop.views import index as interop_index

router = routers.DefaultRouter()
router.register(r'posts', PostViewSet)
router.register(r'comments', CommentViewSet)


urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include(router.urls)),
    path('iris/', index),
    path('interop/', interop_index)
]

• router - REST API のデフォルトのルーターが含まれます。
• routeer.register - Post と Comment ビューセットをルーターに登録します。
• urlpatterns - Django アプリケーションの URL パターンが含まれます。
  • /admin/ - Django 管理インターフェース。
  • /api/ - Post と Comment オブジェクトの REST API。
  • /iris/ - IRIS エンドポイントでの SQL。
  • /interop/ - 相互運用性エンドポイント。

app/wsgi.py

このファイルには、Django アプリケーションの WSGI 構成が含まれます。

これが、Django アプリケーションを実行するために IRIS に提供する必要のあるファイルです。

Security->Applications->Web Applications セクションで、このファイルへのパスを指定する必要があります。

• アプリケーション名
  • app.wsgi
• コーラブル名
  • application
• WSGI アプリディレクトリ
  • /irisdev/app/app

community/models.py

このファイルには、Post と Comment オブジェクトの Django モデルが含まれます。

from django.db import models

# Create your models here.
class Post(models.Model):
    title = models.CharField(max_length=100)
    content = models.TextField()

class Comment(models.Model):
    content = models.TextField()
    post = models.ForeignKey(Post, on_delete=models.CASCADE, related_name='comments')

• Post - Post オブジェクトのモデル。
  • title - 投稿のタイトル。
  • content - 投稿のコンテンツ。
• Comment - Comment オブジェクトのモデル。
  • content - コメントのコンテンツ。
  • post - Post オブジェクトの外部キー。
  • related_name - コメントの関連名。

community/seializers.py

このファイルには、Post と Comment オブジェクトの Django シリアライザーが含まれます。

Django REST フレームワークでは、Django モデルを JSON オブジェクトにシリアル化できます。

from rest_framework import serializers
from community.models import Post, Comment

class PostSerializer(serializers.ModelSerializer):
    class Meta:
        model = Post
        fields = ('id', 'title', 'content', 'comments')

class CommentSerializer(serializers.ModelSerializer):
    class Meta:
        model = Comment
        fields = ('id', 'content', 'post')

• PostSerializer - Post オブジェクトのシリアライザー。
• CommentSerializer - Comment オブジェクトのシリアライザー。
• fields - シリアル化されるフィールド。

community/views.py

このファイルには、Post と Comment オブジェクトの Django ビューが含まれます。

Django REST フレームワークを使て、Django モデルの CRUD 操作を作成できます。

from django.shortcuts import render
from rest_framework import viewsets

# Import the Post and Comment models
from community.models import Post, Comment

# Import the Post and Comment serializers
from community.serializers import PostSerializer, CommentSerializer

# Create your views here.
class PostViewSet(viewsets.ModelViewSet):
    queryset = Post.objects.all()
    serializer_class = PostSerializer

class CommentViewSet(viewsets.ModelViewSet):
    queryset = Comment.objects.all()
    serializer_class = CommentSerializer

• PostViewSet - Post オブジェクトのビューセット。
• CommentViewSet - Comment オブジェクトのビューセット。
• queryset - ビューセットのクエリセット。
• serializer_class - ビューセットのシリアライザークラス。

sqloniris/views.py

このファイルには、IRIS 操作における SQL の Django ビューが含まれます。

from django.http import JsonResponse

import iris

def index(request):
    query = "SELECT top 10 * FROM %Dictionary.ClassDefinition"
    rs = iris.sql.exec(query)
    # Convert the result to a list of dictionaries
    result = []
    for row in rs:
        result.append(row)
    return JsonResponse(result, safe=False)

• index - IRIS 操作における SQL のビュー。
• query - IRIS データベースで実行される SQL クエリ。
• rs - クエリの結果セット。
• result - 結果セットからのリストのリスト。
• JsonResponse - ビューの JSON レスポンス。リストのリスト表示を許可するには safe を False に設定します。

interop/views.py

このファイルには、相互運用性操作における SQL の Django ビューが含まれます。

from django.http import HttpResponse

from grongier.pex import Director

bs = Director.create_python_business_service('BS')

def index(request):
    result = bs.on_process_input(request)
    return HttpResponse(result, safe=False)

• bs - Director クラスを使用して作成されるビジネスサービスオブジェクト。
• index - 相互運用性操作のビュー。
• result - ビジネスサービスの結果。

注: コードを単純化するために JsonResponse は使用しません。JSON オブジェクトを返す場合は使用できます。

トラブルシューティング

スタンドアロンモードで Django アプリケーションを実行する方法

スタンドアロンモードで Django アプリケーションを実行するには、以下のコマンドを使用できます。

cd /irisdev/app/app
python3 manage.py runserver 8001

これは、デフォルトのポート 8001 で Django アプリケーションを実行します。

注: このコマンドを実行するには、コンテナー内にいる必要があります。

docker exec -it iris-django-template-iris-1 bash

IRIS でアプリケーションを再起動する

DEBUG モードでアプリケーションに複数の呼び出しを行うと、変更はアプリケーションに反映されます。

IRIS 管理ポータルへのアクセス方法

http://localhost:53795/csp/sys/UtilHome.csp に移動すると、IRIS 管理ポータルにアクセスできます。

このテンプレートをローカルで実行する

これには、マシンに IRIS がインストールされている必要があります。

次に、IRISAPP というネームスペースを作成する必要があります。

要件をインストールします。

# Move to the app directory
cd /irisdev/app/app

# python manage.py flush --no-input
python3 manage.py migrate
# create superuser
export DJANGO_SUPERUSER_PASSWORD=SYS
python3 manage.py createsuperuser --no-input --username SuperUser --email admin@admin.fr

# load demo data
python3 manage.py loaddata community/fixtures/demo.json

# collect static files
python3 manage.py collectstatic --no-input --clear

# init iop
iop --init

# load production
iop -m /irisdev/app/app/interop/settings.py

# start production
iop --start Python.Production

静的ファイルの配信方法

Django アプリケーションで静的ファイルを配信するには、以下のコマンドを使用できます。

cd /irisdev/app
python3 manage.py collectstatic

これは、Django アプリケーションから静的ファイルを収集して、/irisdev/app/static ディレクトリに配信します。

IRIS で静的ファイルを公開するには、Security->Applications->Web Applications セクションを構成します。

IRIS 2024.3 で発生する2つの製品障害が確認されました。お使いの環境が該当する場合は、それぞれの解決方法にしたがってご対応いただきますよう、よろしくお願いします。

説明

これは、ネイティブウェブアプリケーションとして IRIS にデプロイできる FastAPI アプリケーションのテンプレートです。

インストール

1. リポジトリをクローンする
2. 仮想環境を作成する
3. 要件をインストールする
4. docker-compose ファイルを実行する

git clone
cd iris-fastapi-template
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
docker-compose up

使用法

ベース URL は http://localhost:53795/fastapi/ です。

エンドポイント

• /iris - IRISAPP ネームスペースに存在する上位 10 個のクラスを持つ JSON オブジェクトを返します。
• /interop - IRIS の相互運用性フレームワークをテストするための ping エンドポイント。
• /posts - Post オブジェクトの単純な CRUD エンドポイント。
• /comments - Comment オブジェクトの単純な CRUD エンドポイント。

このテンプレートからの開発方法

WSGI 導入記事をご覧ください: wsgiサポートの概要。

概要: セキュリティポータルで DEBUG フラグをトグルすると、開発作業の過程で変更内容がアプリケーションに反映されるようになります。

コードの説明

app.py

これは FastAPI アプリケーションのメインのファイルです。 FastAPI アプリケーションとルートが含まれます。

from fastapi import FastAPI, Request

import iris

from grongier.pex import Director

# import models
from models import Post, Comment, init_db
from sqlmodel import Session,select

app = FastAPI()

# create a database engine
url = "iris+emb://IRISAPP"
engine = init_db(url)

• from fastapi import FastAPI, Request - FastAPI クラスト Request クラスをインポートします。
• import iris - IRIS モジュールをインポートします。
• from grongier.pex import Director: Flask アプリを IRIS 相互運用性フレームワークにバインドする Director クラスをインポートします。
• from models import Post, Comment, init_db - モデルと init_db 関数をインポートします。
• from sqlmodel import Session,select - Session クラスと sqlmodel モジュールの選択された関数をインポートします。
• app = FastAPI() - FastAPI アプリケーションを作成します。
• url = "iris+emb://IRISAPP" - IRIS ネームスペースの URL を定義します。
• engine = init_db(url) - sqlmodel ORM のデータベースエンジンを作成します。

models.py

このファイルには、アプリケーションのモデルが含まれます。

from sqlmodel import Field, SQLModel, Relationship, create_engine

class Comment(SQLModel, table=True):
    id: int = Field(default=None, primary_key=True)
    post_id: int = Field(foreign_key="post.id")
    content: str
    post: "Post" = Relationship(back_populates="comments")

class Post(SQLModel, table=True):
    id: int = Field(default=None, primary_key=True)
    title: str
    content: str
    comments: list["Comment"] = Relationship(back_populates="post")

説明することは特にありません。外部キーとリレーションによる単なるモデルの定義です。

init_db 関数は、データベースエンジンの作成に使用されます。

def init_db(url):

    engine = create_engine(url)

    # create the tables
    SQLModel.metadata.drop_all(engine)
    SQLModel.metadata.create_all(engine)

    # initialize database with fake data
    from sqlmodel import Session

    with Session(engine) as session:
        # Create fake data
        post1 = Post(title='Post The First', content='Content for the first post')
        ...
        session.add(post1)
        ...
        session.commit()

    return engine

• engine = create_engine(url) - データベースエンジンを作成します。
• SQLModel.metadata.drop_all(engine) - すべてのテーブルをドロップします。
• SQLModel.metadata.create_all(engine) - すべてのテーブルを作成します。
• with Session(engine) as session: - データベースを操作するためのセッションを作成します。
• post1 = Post(title='Post The First', content='Content for the first post') - Post オブジェクトを作成します。
• session.add(post1) - Post オブジェクトをセッションに追加します。
• session.commit() - 変更内容をデータベースにコミットします。
• return engine - データベースエンジンを返します。

/iris エンドポイント

######################
# IRIS Query example #
######################

@app.get("/iris")
def iris_query():
    query = "SELECT top 10 * FROM %Dictionary.ClassDefinition"
    rs = iris.sql.exec(query)
    # Convert the result to a list of dictionaries
    result = []
    for row in rs:
        result.append(row)
    return result

• @app.get("/iris") - /iris エンドポイントの GET ルートを定義します。
• query = "SELECT top 10 * FROM %Dictionary.ClassDefinition" - IRIS ネームスペースで上位 10 個のクラスを取得するクエリを定義します。
• rs = iris.sql.exec(query) - クエリを実行します。
• result = [] - 結果を保存する空のリストを作成します。
• for row in rs: - 結果セットを反復処理します。
• result.append(row) - 結果リストを行にアペンドします。
• return result - 結果リストを返します。

/interop エンドポイント

########################
# IRIS interop example #
########################
bs = Director.create_python_business_service('BS')

@app.get("/interop")
@app.post("/interop")
@app.put("/interop")
@app.delete("/interop")
def interop(request: Request):
    
    rsp = bs.on_process_input(request)

    return rsp

• bs = Director.create_python_business_service('BS') - Python ビジネスサービスを作成します。
  • ビジネスサービスの複数のインスタンスを防止するために、ルート定義の外に作成する必要があります。
• @app.get("/interop") - /interop エンドポイントの GET ルートを定義します。
• @app.post("/interop") - /interop エンドポイントの POST ルートを定義します。
• ...
• def interop(request: Request): - ルートハンドラーを定義します。
• rsp = bs.on_process_input(request) - ビジネスサービスの on_process_input メソッドを呼び出します。
• return rsp - レスポンスを返します。

/posts エンドポイント

############################
# CRUD operations posts    #
############################

@app.get("/posts")
def get_posts():
    with Session(engine) as session:
        posts = session.exec(select(Post)).all()
        return posts
    
@app.get("/posts/{post_id}")
def get_post(post_id: int):
    with Session(engine) as session:
        post = session.get(Post, post_id)
        return post
    
@app.post("/posts")
def create_post(post: Post):
    with Session(engine) as session:
        session.add(post)
        session.commit()
        return post

このエンドポイントは、Post オブジェクトで CRUD 操作を実行するために使用されます。

説明することは特にありません。すべての投稿を取得し、ID で投稿を取得し、投稿を作成するためのルートの定義です。

すべては sqlmodel ORM を使って行われます。

/comments エンドポイント

############################
# CRUD operations comments #
############################


@app.get("/comments")
def get_comments():
    with Session(engine) as session:
        comments = session.exec(select(Comment)).all()
        return comments
    
@app.get("/comments/{comment_id}")
def get_comment(comment_id: int):
    with Session(engine) as session:
        comment = session.get(Comment, comment_id)
        return comment
    
@app.post("/comments")
def create_comment(comment: Comment):
    with Session(engine) as session:
        session.add(comment)
        session.commit()
        return comment

このエンドポイントは、Comment オブジェクトで CRUD 操作を実行するために使用されます。

説明することは特にありません。すべてのコメントを取得し、ID でコメントを取得し、コメントを作成するためのルートの定義です。

すべては sqlmodel ORM を使って行われます。

トラブルシューティング

スタンドアロンモードで FastAPI アプリケーションを実行する方法

以下のコマンドを使用して、いつでもスタンドアロンの Flask アプリケーションを実行できます。

python3 /irisdev/app/community/app.py

注: このコマンドを実行するには、コンテナー内にいる必要があります。

docker exec -it iris-fastapi-template-iris-1 bash

IRIS でアプリケーションを再起動する

DEBUG モードでアプリケーションに複数の呼び出しを行うと、変更はアプリケーションに反映されます。

IRIS 管理ポータルへのアクセス方法

http://localhost:53795/csp/sys/UtilHome.csp に移動すると、IRIS 管理ポータルにアクセスできます。

このテンプレートをローカルで実行する

これには、マシンに IRIS がインストールされている必要があります。

次に、IRISAPP というネームスペースを作成する必要があります。

要件をインストールします。

IoP のインストール:

#init iop
iop --init

# load production
iop -m /irisdev/app/community/interop/settings.py

# start production
iop --start Python.Production

セキュリティポータルでアプリケーションを構成します。

説明

これは、ネイティブウェブアプリケーションとして IRIS にデプロイできる Flask アプリケーションのテンプレートです。

インストール

1. リポジトリをクローンする
2. 仮想環境を作成する
3. 要件をインストールする
4. docker-compose ファイルを実行する

git clone
cd iris-flask-template
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
docker-compose up

使用法

ベース URL は http://localhost:53795/flask/ です。

エンドポイント

• /iris - IRISAPP ネームスペースに存在する上位 10 個のクラスを持つ JSON オブジェクトを返します。
• /interop - IRIS の相互運用性フレームワークをテストするための ping エンドポイント。
• /posts - Post オブジェクトの単純な CRUD エンドポイント。
• /comments - Comment オブジェクトの単純な CRUD エンドポイント。

このテンプレートからの開発方法

WSGI 導入記事をご覧ください: wsgi-introduction。

概要: セキュリティポータルで DEBUG フラグをトグルすると、開発作業の過程で変更内容がアプリケーションに反映されるようになります。

コードの説明

app.py

これはアプリケーションのメインのファイルです。 Flask アプリケーションとエンドポイントが含まれます。

from flask import Flask, jsonify, request
from models import Comment, Post, init_db

from grongier.pex import Director

import iris

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = 'iris+emb://IRISAPP'

db = init_db(app)

• from flask import Flask, jsonify, request: Flask ライブラリをインポートします。
• from models import Comment, Post, init_db: モデルとデータベース初期化関数をインポートします。
• from grongier.pex import Director: Flask アプリを IRIS 相互運用性フレームワークにバインドする Director クラスをインポートします。
• import iris: IRIS ライブラリをインポートします。
• app = Flask(__name__): Flask アプリケーションを作成します。
• app.config['SQLALCHEMY_DATABASE_URI'] = 'iris+emb://IRISAPP': データベース URI を IRISAPP ネームスペースに設定します。
  • iris+emb URI スキームは、埋め込み接続として IRIS に接続するために使用されます（別の IRIS インスタンスの必要はありません）。
• db = init_db(app): Flask アプリケーションでデータベースを初期化します。

models.py

このファイルには、アプリケーションの SQLAlchemy モデルが含まれます。

from dataclasses import dataclass
from typing import List
from flask_sqlalchemy import SQLAlchemy

db = SQLAlchemy()

@dataclass
class Comment(db.Model):
    id:int = db.Column(db.Integer, primary_key=True)
    content:str = db.Column(db.Text)
    post_id:int = db.Column(db.Integer, db.ForeignKey('post.id'))

@dataclass
class Post(db.Model):
    __allow_unmapped__ = True
    id:int = db.Column(db.Integer, primary_key=True)
    title:str = db.Column(db.String(100))
    content:str = db.Column(db.Text)
    comments:List[Comment] = db.relationship('Comment', backref='post')

説明することは特にありません。モデルはデータクラスとして定義されており、db.Model クラスのサブクラスです。

__allow_unmapped__ 属性は、comments 属性を使用せずに Post オブジェクトを作成できるようにするために使用する必要があります。

dataclasses はオブジェクトを JSON にシリアル化するのに使用されます。

init_db 関数は、Flask アプリケーションでデータベースを初期化します。

def init_db(app):
    db.init_app(app)

    with app.app_context():
        db.drop_all()
        db.create_all()
        # Create fake data
        post1 = Post(title='Post The First', content='Content for the first post')
        ...
        db.session.add(post1)
        ...
        db.session.commit()
    return db

• db.init_app(app): Flask アプリケーションでデータベースを初期化します。
• with app.app_context(): アプリケーションのコンテキストを作成します。
• db.drop_all(): データベースのすべてのテーブルをドロップします。
• db.create_all(): データベースのすべてのテーブルを作成します。
• アプリケーションの偽データを作成します。
• データベースオブジェクトを返します。

/iris エンドポイント

######################
# IRIS クエリ例 #
######################

@app.route('/iris', methods=['GET'])
def iris_query():
    query = "SELECT top 10 * FROM %Dictionary.ClassDefinition"
    rs = iris.sql.exec(query)
    # Convert the result to a list of dictionaries
    result = []
    for row in rs:
        result.append(row)
    return jsonify(result)

このエンドポイントは、IRIS データベースでクエリを実行し、IRISAPP ネームスペースに存在する上位 10 個のクラスを返します。

/interop エンドポイント

########################
# IRIS interop example #
########################
bs = Director.create_python_business_service('BS')

@app.route('/interop', methods=['GET', 'POST', 'PUT', 'DELETE'])
def interop():
    
    rsp = bs.on_process_input(request)

    return jsonify(rsp)

このエンドポイントは、IRIS の相互運用性フレームワークをテストするために使用されます。 ビジネスサービスオブジェクトを作成し、それを Flask アプリケーションにバインドします。

注: bs オブジェクトは有効な状態を維持するために、リクエストの範囲外にある必要があります。

• bs = Director.create_python_business_service('BS'): 'BS' というビジネスサービスオブジェクトを作成します。
• rsp = bs.on_process_input(request): リクエストオブジェクトを引数としてビジネスサービスオブジェクトの on_process_input メソッドを呼び出します。

/posts エンドポイント

############################
# CRUD operations posts    #
############################

@app.route('/posts', methods=['GET'])
def get_posts():
    posts = Post.query.all()
    return jsonify(posts)

@app.route('/posts', methods=['POST'])
def create_post():
    data = request.get_json()
    post = Post(title=data['title'], content=data['content'])
    db.session.add(post)
    db.session.commit()
    return jsonify(post)

@app.route('/posts/<int:id>', methods=['GET'])
def get_post(id):
    ...

このエンドポイントは、Post オブジェクトで CRUD 操作を実行するために使用されます。

dataclasses モジュールにより、Post オブジェクトは簡単に JSON にシリアル化できます。

以下では、すべての投稿を取得する sqlalchemy の query メソッドと、新しい投稿を作成するための add と commit メソッドを使用しています。

/comments エンドポイント

############################
# CRUD operations comments #
############################

@app.route('/comments', methods=['GET'])
def get_comments():
    comments = Comment.query.all()
    return jsonify(comments)

@app.route('/comments', methods=['POST'])
def create_comment():
    data = request.get_json()
    comment = Comment(content=data['content'], post_id=data['post_id'])
    db.session.add(comment)
    db.session.commit()
    return jsonify(comment)

@app.route('/comments/<int:id>', methods=['GET'])
def get_comment(id):
    ...

このエンドポイントは、Comment オブジェクトで CRUD 操作を実行するために使用されます。

Comment オブジェクトは外部キーによって Post オブジェクトにリンクされます。

トラブルシューティング

スタンドアロンモードで Flask アプリケーションを実行する方法

以下のコマンドを使用して、いつでもスタンドアロンの Flask アプリケーションを実行できます。

python3 /irisdev/app/community/app.py

注: このコマンドを実行するには、コンテナー内にいる必要があります。

docker exec -it iris-flask-template-iris-1 bash

IRIS でアプリケーションを再起動する

DEBUG モードでアプリケーションに複数の呼び出しを行うと、変更はアプリケーションに反映されます。

IRIS 管理ポータルへのアクセス方法

http://localhost:53795/csp/sys/UtilHome.csp に移動すると、IRIS 管理ポータルにアクセスできます。

このテンプレートをローカルで実行する

これには、マシンに IRIS がインストールされている必要があります。

次に、IRISAPP というネームスペースを作成する必要があります。

要件をインストールします。

IoP のインストール:

#init iop
iop --init

# load production
iop -m /irisdev/app/community/interop/settings.py

# start production
iop --start Python.Production

セキュリティポータルでアプリケーションを構成します。

コンテキスト

ウェブサーバーゲートウェイインターフェース（WSGI）は、ウェブサーバーがリクエストを Python プログラミング言語で記述されたウェブアプリケーションまたはフレームワークに転送するための単純な呼び出し規則です。 WSGI は PEP 3333 で詳しく説明された Python 規格です。

🤔 定義は良いとして、IRIS との関連性は何でしょうか？

IRIS 2024.2+ の新機能により、直接 IRIS で WSGI アプリケーションを実行できます。 この機能は、IRIS を他の Python フレームワークとライブラリに統合する優れた方法です。

これは、Python を使用して IRIS と対話できる Python ファーストエクスペリエンスのトレンドに沿ったもので、Python アプリケーションを IRIS 上で直接実行することもできるようになりました。

使用方法

IRIS で WSGI アプリケーションをインスタンス化するには、IRIS 管理ポータルのセキュリティ -> アプリケーション -> ウェブアプリケーションのセクションで構成する必要があります。

単純な Flask の例:

/irisdev/app/community ディレクトリにある app.py というファイル:

from flask import Flask

app = Flask(__name__)

@app.route('/')
def hello_world():
    return 'Hello, World!'

UI 構成

このセクションでは、以下を指定することで WSGI アプリケーションを構成できます。

• アプリケーション名

• これは WSGI アプリケーションのファイル名に対応します

• 例: app.py ですが、.py 拡張子を除きます : app

• コーラブル名

  • WSGI サーバーによって呼び出されるコーラブル関数

  • 例: app は、app.py ファイルの app 変数に対応します

    • app = Flask(__name__)

• WSGI アプリディレクトリ

  • WSGI アプリケーションが存在するパス
  • 例: /irisdev/app/community

• Python プロトコルタイプ

  • wsgi またｈ asgi
    • wsgi はデフォルト値で、この例で使用されているタイプです
    • asgi は非同期アプリケーションに使用します
      • asgi は現時点では a2wsgi アダプターによって同期的にサポートされています

• デバッグ

  • オンの場合、WSGI アプリケーションはデバッグモードで実行します
    • WSGI アプリケーションへの変更は自動的に再読み込みされるため、開発目的において便利です

CPF マージ

CPF を使用して WSGI アプリケーションを構成することも可能です。 構成の例を以下に示します。

[Actions]
CreateApplication:Name=/flask,NameSpace=IRISAPP,WSGIAppLocation=/irisdev/app/community/,WSGIAppName=app,WSGICallable=app,Type=2,DispatchClass=%SYS.Python.WSGI,MatchRoles=:%ALL,WSGIDebug=0,WSGIType=0

ログファイル

WSGI アプリケーションログは、インスタンスの mgr ディレクトリにある WSGI.log ファイルに保存されます。

例

以下は、IRIS で実行できる WSGI アプリケーションの例です。IRIS で様々な Python フレームワークを実行する方法を示すことを目的としています。

基本的に、ユースケースはすべてのフレームワークで同一です。

エンドポイント

• /iris - IRISAPP ネームスペースに存在する上位 10 個のクラスを持つ JSON オブジェクトを返します。
• /interop - IRIS の相互運用性フレームワークをテストするための ping エンドポイント。
• /posts - Post オブジェクトの単純な CRUD エンドポイント。
• /comments - Comment オブジェクトの単純な CRUD エンドポイント。

オブジェクトモデル

Post オブジェクト:

• id
• title
• content

Comment オブジェクト:

• id
• post_id（Post の外部キー）
• content

Flask

• Github: iris-flask-template
• 記事: running-flask-applications-iris

Django

• Github: iris-django-template
• 記事: running-django-applications-iris

FastAPI

• Github: iris-fastapi-template
• 記事: running-fastapi-applications-iris

制限

• ASGI は現時点では a2wsgi アダプターによって同期的にサポートされています。
• tornado アプリケーション（jupyter、streamlit など ）は、WSGI に対応していないためサポートされていません。

InterSystems IRIS 2021.2 のバージョンより、Embedded Python を使用できるようになりました。

Embedded Python で Excel のデータを IRIS グローバルに格納する方法 では pandas.DataFrame のデータを InterSystems IRIS グローバルに保存する方法をご紹介しました。
こちらの記事では、その逆の「InterSystems IRIS グローバル($LB) を pandas.DataFrame に変換する」方法をご紹介します。

以下のようなグローバルを、Embedded Python を使用して DataFrame に変換します。

USER>zwrite^ISJ^ISJ=4^ISJ(1)=$lb("Name","Age","Address")
^ISJ(2)=$lb("佐藤","50","東京")
^ISJ(3)=$lb("加藤","40","大阪")
^ISJ(4)=$lb("伊藤","30","京都")

%Library.GlobalクラスのGetクエリ を使用して取得し、iris.sql.execを使用して DataFrame に格納する方法があります。
ただし、こちらの方法はリスト形式($LB)のまま DataFrame に変換します。

開発者の皆さん、こんにちは。

Teams ワークフロー Webhook を用意すると、curl コマンドや REST クライアントを利用して Teams チャネルに任意メッセージを簡単に送信できるので、IRIS や IRIS の Interoperability を使って自動的に何か情報を入手＋必要なときだけ Teams チャネル通知ができたら面白いな、と思い試してみた内容をご紹介します。

以下、Teamsワークフローの作成例です。

Teams ワークフローの仕様に合わせたメッセージ用 JSON が用意できれば、こんなメッセージを出すことができます。

Teams チャネルにメッセージを通知するには「Teams ワークフローの Webhook」の用意が必要です。（この用意によってアクセスするために必要なURLが生成されます）詳しくは、「Microsoft Teamsのワークフローを使用して受信 Webhook を作成する」をご参照ください。

通知までの設定などについては、こちらのページを参考にさせていただきました：Teams チャネルへメッセージ送信する方法

以下、試した順でご紹介します。

1. curl コマンドでまずは実行してみる

2. シンプルにターミナルから試す

3. 通知メッセージのJSONを変えてみる

4. メッセージのJSONをJSONテンプレートエンジンで作ってみる

Mac版IRISでは、現状Pythonのバージョンが固定(3.11)なのですが、これに付随する他製品との相性問題に遭遇しましたので報告します。

今までEmbedded Pythonは調子よく動作していたのですが、ある時から急に動作しなくなりました。

原因を調べてみると、Python3.13がインストールされ、それがデフォルトとして上書きされたため、irispythonコマンドを発行すると、それが内部で3.13を呼ぶ様になってしまったためでした。

ちなみにiris session でログインし、そこからEmbedded Pythonを実行する場合は、問題ありません。

あくまでもirispythonコマンドで直接.pyファイルを実行する場合に発生する問題です。

そしてとりあえずの対処法は、python3をpython3.11で置き換える方法です。

以下のような感じです。（どのMacでもbrewコマンドでインストールした場合、ディレクトリ構造は同じだと思いますが、違う可能性もゼロではありません）

cp /opt/homebrew/bin/python3.11 /opt/homebrew/bin/python3

さて、ところで何で3.13がインストールされていたのかというと、

IRIS SQLのLOADコマンドを動作させるためには、JDKまたはJREが必要なのでそれをインストールしました。

コミュニティメンバーから、Python 2024 コンテストでの出品に対する非常に素晴らしいフィードバックが届きました。 ここで紹介させていただきます。

純粋な IRIS の 5 倍以上のサイズでコンテナーをビルドしているため、時間がかかっています

コンテナーの始動も時間はかかりますが、完了します

バックエンドは説明通りにアクセス可能です

プロダクションは稼動しています

フロントエンドは反応します

何を説明したいのかがよくわかりません

私以外のエキスパート向けに書かれた説明のようです

出品はこちら: https://openexchange.intersystems.com/package/IRIS-RAG-App

このようなフィードバックをいただけて、本当に感謝しています。プロジェクトに関する記事を書く素晴らしいきっかけとなりました。 このプロジェクトにはかなり包括的なドキュメントが含まれてはいますが、ベクトル埋め込み、RAG パイプライン、LLM テキスト生成のほか、Python や LLamaIndex などの人気の Python ライブラリに精通していることが前提です。

この記事は、IRIS での RAG ワークフローを実証するに当たって、上記の前提事項や、それらが IRIS で RAG ワークフローをこのプロジェクトにどのように適合するかについてを説明する試みです。AI をまったく使用せずに書かれています。

コンテナーが大きいのは、ベクトル埋め込みの作成に関わる Python パッケージに必要なライブラリ依存関係が非常に大きいためです。 より選択的にインポートすることで、サイズを大幅に縮小することが可能です。

コンテナーの初回ビルドには確かに時間がかかりますが、一度ビルドすれば起動時間は短くなります。 とはいえ、起動時間は確かに改善できるかもしれません。 起動にこれほどの時間がかかる主な理由は、アプリケーションのある個所が最後の起動から変更されていることを想定して entrypoint.sh が更新されているためです。これには、データベースの移行、CSS 構成、JavaScript 構成、Python バックエンドコードも含まれており、起動のたびにプロジェクト全体がリコンパイルされます。 これは、このプロジェクトを開発し始めやすくするためで、そうでない場合は、変更が適用されるたびに、フロントエンドとバックエンドのビルドを適切に実行するのが困難になってしまいます。 こうすることで、プロジェクトのコードを変更した場合はコンテナーを再起動し、場合によってはバックエンドのプロダクションを復旧すれば、アプリケーションのインターフェースと操作に変更が反映されます。

バックエンドのプロダクションは、HTTP リクエストを Django アプリケーションに渡すものであり、このパッケージの相互運用性にとって非常に重要であると確信しています。 ただし、私自身は IRIS プラットフォームの初心者であるため、プロダクションについてもっと学ぶ必要があります。

次に、ベクトル埋め込み、LLM、および RAG について、包括的に説明したいと思います。 この内最初に作られたのはベクトル埋め込みです。 まず、ベクトルについて説明します。 ほとんどのコンテキストにおいて、ベクトルは方向です。 空間のどこかを指す矢印です。 より正式には、ベクトルは「大きさだけでなく方向も持つ量」です。 これは、特定の方向へ移動し、空間内の特定の地点で爆発する花火によって例えることができます。 すべての花火が同じ中心点、つまり原点である [0,0,0] から発射され、その原点の周囲に雲となって飛び散るとします。 数学的には、3 つの座標系 [x,y,z] を使用して各花火の爆発の位置を表現することができ、これが花火の爆発の「ベクトル埋め込み」となります。 花火のビデオをたくさん撮影し、花火の爆発をすべてデータセットとして記録すると、花火の一種のベクトル埋め込みデータベース、つまりベクトルストアが作成されることになります。

花火に関する情報を使って何ができるでしょうか？ 特定の花火を指して、花火全体の中から同じ点に最も近い位置で爆発した花火について尋ねると、空間の近くの点で爆発した他の花火を検索できます。 最もちかいものを見つけるだけですが、これを行うために数式があります。

花火ごとに、x、y、z の 3 つの数値のみを記録したことに注意してください。3 次元空間において、地上の花火発射台を [0,0,0] としています。

他の特定の花火に対して、距離と時間の両方の観点で最も近く爆発した花火も知りたい場合はどうでしょうか？ それを知るには、花火の映像を確認して、各爆発の時間も記録しなければなりません。 これで、4 つの数値を持つ 4 次元ベクトルが取得されました。花火の爆発の 3 次元の位置に爆発の時間を加えたベクトルです。 ベクトル埋め込みにもう 1 つの次元を追加することで、花火の埋め込みがより記述的になりました。

これを機械学習に変換するとどうなるでしょうか？ 手短に言えば、大量のテキストデータを処理することで、コンピューター科学者は、フレーズ、文章、段落、またはページなどのテキストを変換し、理論的な高次元空間の点を表現する非常に長い一連の数値に変換できる埋め込みモデルを作成することができました。

4 つの数字ではなく、300、700、さらには 1500 もの数字があります。 これらは、1 つのテキストが互いに「近い」か「遠い」かを 1500 通りまたは1500 次元の意味で表します。 テキストの意味を何らかの方法で表す数字を作成する手段があるというわけですから、多くの人にとって魅力的な概念と言えるでしょう。

数学を使用すると、これらの高次元テキストベクトル埋め込みのうち 2 つを比較して、同じモデルによって作成された場合に、それらが互いにどの程度類似しているか、つまり「近い」かを調べることができます。

このアプリで最初の行われているのが正にこれです。ユーザーはドキュメントを追加して名前を付け、埋め込みのタイプを選択する必要があります。 サーバーはそのドキュメントを受け取り、テキストのチャンクに分割してから、それぞれのチャンクをベクトル埋め込みに変換します。そのチャンクはそのドキュメントの専用のテーブルの行として保存されます。 各ドキュメントは、さまざまなテキスト埋め込みモデルによって作成されるベクトル埋め込みの可変長に対応できるように、それぞれの専用テーブルに保存されます。

ドキュメントがベクトル埋め込みとしてデータベースに保存されると、ユーザーはドキュメントに「尋ねる」クエリを入力できるようになります。 このクエリは 2 つの方法で使用されます。 1 つは、ドキュメントを検索するためです。 従来のテキスト検索は実行せずに、「ベクトル検索」を実行します。 アプリはクエリを受け取り、それをベクトル埋め込みに変換してから、クエリベクトル埋め込みに最も築地する埋め込みのあるドキュメントのセクションを検索します。 各ドキュメントセクションには 0 と 1 の間の類似性スコアが生成され、top_k_similarity と similarity_threshold に基づいて、ベクトルデータベースから複数のセクションが検索されます。 基本的に、取得するドキュメントのセクション数と取得の対象となるためにクエリとどの程度類似している必要があるかを指定することができます。

これが、検索拡張生成における取得です。 次は生成に移りましょう。

コンピューター科学者がテキストを意味的に重要な数値ベクトル埋め込みに変換する方法を見つけると、次に、テキストを生成するモデルの作成に移りました。 これは大きな成功を生み出し、現在では GPT-4、LLama3、Claude 3.5 などの大規模言語モデルとなっています。 これらの LLM はプロンプトまたはクエリを受け取り、補完または回答を提供します。これは LLM が提示されたテキストであるプロンプトから最も続行できる可能性があると考えるテキストです。

LLM は大量のテキストデータに対してトレーニングする必要があり、その回答または補完はそのトレーニングデータに制限されます。 トレーニングセットにないデータを含む可能性のある補完を LLM に提供させる場合、または補完を特定のナレッジセットに基づかせる場合は、1 つの方法として、プロンプトに追加のコンテキストデータを含めることができます。 基本的に、トレーニングされていない内容について LLM から回答を得たい場合、プロンプトに情報を提供する必要があるということです。

多くの人は、ChatGPT やローカルの LLama インストールが自分の個人文書に基づいて回答を提供してくれることを望む状況に陥っていました。 ドキュメント内でその情報を検索し、プロンプトに貼り付けて、質問を入力するだけの単純な操作であり、手作業で行っていました。 それ自体が検索拡張生成です。 RAG は、より正確または利便的な応答を得られるように、ユーザークエリに関連する情報を検索し、LLM にクエリを提供する操作を自動化したに過ぎません。

このアプリでは、ベクトル検索で取得したドキュメントセクションは、インターフェースでモデルとしてラベル付けされている選択された LLM にクエリとともに送信され、回答のコンテキストが提供されます。

このプロジェクト用に制作した動画の例では、シェイクスピアの 2 つの戯曲の全文を含むドキュメント「ハムレット」と「リア王」を使って、「この戯曲の悪役は誰ですか？」と尋ねています。 IRIS データベースには、ハムレットとリア王の 2 つのテーブルがすでに存在します。 各テーブルには、各戯曲のテキストをセクションに分割して作成されたベクトル埋め込みの行が入力されています。 これらの埋め込みは、一連の長い数値によって各ドキュメントセクションの多次元を表現しています。

サーバーは、「この戯曲の悪役は誰ですか」という質問を、リア王のベクトル埋め込みを生成した Text-to-Vector モデルを使用して数値ベクトルに変換し、リア王テーブル内でそれに最も類似するセクションを見つけます。 これらはおそらく悪役という語が言及されたセクションかもしれませんが、悪役が明示的に言及されていない場合でも、裏切り、裏切り、欺瞞などの他の悪役についても言及されている可能性があります。 こういったドキュメントのセクションは、クエリに追加され、合わせてプロンプトとして LLM に送信されます。LLM は提供されたドキュメントのセクションに基づいて質問に回答します。

これはドキュメントごとに個別に実行されるため、クエリの回答はクエリされているドキュメントに応じて異なります。 これにより頭字語が補完されます。ベクトル検索の力を使用して関連するコンテキスト情報を取得することで、LLM からの応答の生成を強化しているためです。

この記事をお読みいただきありがとうございました。このトピックについては今後の記事でも発展させたいと思います。 フィードバックをお待ちしています。

コミュニティの皆さんこんにちは。

突然ですが、皆さんはIRISの機能にある「ユニットテスト」は利用されているでしょうか。
筆者はまだ実装まで行えていませんが、各関数の品質保証を担保するため導入を検討している段階です。

現状、IRISのユニットテストには下記２点の対応すべき点があると考えています。

1. テスト結果の可読性が低い(先日vscodeで拡張機能が出ていましたが、やはり見ずらいと感じました)
2. ユニットテストを自動で実行する手段がない

特にテストが継続的に自動で実施されないと、ユニットテスト自体が次第に陳腐化し、実行されなくなり忘れ去られる恐れがあると考えます。
ただし、意味もなく定期的にテストを実行しても効果がありません。
そこで、Gitのpushのタイミングで行おうと考えました。

次にテスト環境です。
テスト環境の構築は、テスト自動化の観点からみるとCI/CDツール等を利用するのが一般的だと思います。
ただ今回は、テスト環境の構築を簡易にすませたいと考え、IRISの既存技術を組み合わせて構築しようと考えました。

そこで運用幅の広いInteroperabilityとユニットテストを組み合わせて、テストの自動化が可能か考察していきたいと思います。

【ユニットテスト全体概要】

【全体の流れ】

　■ユーザの開発環境

　　①ユーザは改修したクラスをGitへpushする

　■Git用のサーバ

開発者の皆さん、こんにちは！

この記事は、2024年7月に開催された「InterSystems Pythonプログラミングコンテスト2024」でエキスパート投票、コミュニティ投票の両方で1位を獲得された @Henry Pereira Pereira さん @José Pereira さん @Henrique Dias Dias さんが開発された sqlzilla について、アプリを動かしてみた感想と、中の構造について @José Pereira さんが投稿された「Text to IRIS with LangChain」の翻訳をご紹介します。

第2回 InterSystems Japan 技術文書ライティングコンテスト 開催！ では、生成AIに関連する記事を投稿いただくと、ボーナスポイントを4点獲得できます📢 @José Pereira さんの記事を💡ヒント💡に皆様の操作体験談、アイデアなどを共有いただければと思います。

開発されたアプリSQLzilla についての概要ですが、Open Exchange の sqlzilla のREADMEに以下のように紹介されています。

「SQLzilla は、Python と AI のパワーを活用して、自然言語の SQL クエリ生成を通じてデータ アクセスを簡素化し、複雑なデータ クエリとプログラミング経験の少ないユーザーとの間のギャップを埋めます。」

「SQLクエリ生成」とありますので、アプリには Aviationスキーマ以下3つのテーブルとサンプルデータが用意されています。

• Aviation.Aircraft
• Aviation.Crew
• Aviation.Event

3つのテーブルには、米国国家運輸安全委員会に報告された航空事故の選択されたサブセットのデータが含まれています。

メモ： サンプルリポジトリ で提供されるデータセットは、http://www.ntsb.gov から入手できる完全な NTSB データセットの小さなサブセットであるためデモ目的のみで提供されており、正確であることを意図または保証するものではありません。（提供元：National Transportation Safety Board）

例えば、Aviation.Aircraftには、AircraftCategoryカラムがあり、航空機の種別が登録されています。

[SQL]IRISAPP>>SELECT AircraftCategory FROM Aviation.Aircraft GROUP BY AircraftCategory
1.      SELECT AircraftCategory FROM Aviation.Aircraft GROUP BY AircraftCategory

| AircraftCategory |
| -- |
| AIRPLANE |
| HELICOPTER |
| GYROCRAFT |
| GLIDER |
| BALLOON |
| POWERED PARACHUTE |
| WEIGHT SHIFT |

また、DepartureCity には、出発都市名が登録されています。

SELECT top 10 DepartureCity FROM Aviation.Aircraft WHERE AircraftCategory='AIRPLANE' GROUP BY DepartureCity

| DepartureCity |
| -- |
| WILBUR |
| IRONWOOD |
| STANIEL CAY |
| OAK ISLAND |
| CLEVELAND |
| DECATUR |
| MARSHALLTOWN |
| MARANA |
| TONOPAH |
| MURRIETA/TEMECU |

また、Aviation.Eventテーブルには発生した事故の情報が含まれていて、InjuriesHighestには負傷者数の状況を文字で表現した情報が含まれています。

SELECT InjuriesHighest FROM Aviation.Event GROUP BY InjuriesHighest

| InjuriesHighest |
| -- |
| NONE |
| FATAL |
| SERIOUS |
| MINOR |

さて、これらのテーブルを使って具体的にどのようなことをしてくれるアプリなのか？ですが（説明文より以下抜粋）

「SQLzilla は、ユーザーがデータベースを操作する方法を変革する革新的なプロジェクトです。InterSystems IRIS と統合することで、SQL に詳しくないユーザーでもさまざまなテーブルからデータを簡単に抽出して分析できるツールを作成しました。」

つまり、

SQLに詳しくないユーザでも、自分の欲しい情報に対して質問するとSQLを組み立てて返してきてくれる便利アプリということになります。

以下、アプリケーションを動作させてみたときの図です。（日本語で質問してもしっかりSQLを組み立ててくれています！）

入力した質問によって生成されたSQLは以下の通りです。

• ヘリコプターによる事故の件数を教えてください。

SELECT COUNT(*) FROM Aviation.Aircraft WHERE AircraftCategory = 'Helicopter'

• 2002年に発生したヘリコプターによる事故の件数を教えてください。

SELECT COUNT(*) FROM Aviation.Event WHERE YEAR(EventDate) = 2002 AND Type = 'Helicopter Accident'

• ヘリコプターによる事故でInjuriesHighestがFATALの事故数を年別で表示してください。

SELECT YEAR(e.EventDate) AS IncidentYear, COUNT(*) AS FatalIncidentCount FROM Aviation.Event e JOIN Aviation.Aircraft a ON e.EventId = a.EventId WHERE a.AircraftCategory = 'Helicopter' AND e.InjuriesHighest = 'FATAL' GROUP BY YEAR(e.EventDate)

アプリ詳細は、ぜひ Open Exchange の sqlzilla をご参照ください。

素晴らしいです！！

※ このサンプルを動作させるためには、OpenAIのAPIキーが必要となりますので、お試しになる場合は事前にご準備ください。

Open Exchange の sqlzilla のREADMEにも記載がありますが、コンテナを使う場合は以下3コマンドでサンプルを動作させることができます。

まずはソースコードをclone して

git clone https://github.com/musketeers-br/sqlzilla.git

コンテナをビルドし

docker-compose build --no-cache --progress=plain

コンテナを開始するだけ

docker-compose up -d

後は、アプリ画面を起動するだけ！

コンテナ以外でも操作する方法が提供されています。詳しくは、 sqlzilla のREADMEご参照ください。（ぜひREADMEの一番下までご覧ください！）

記事の紹介

アプリの中でどのようにSQLを生成させているか、については、 @José Pereira さんが投稿された「Text to IRIS with LangChain」の翻訳記事でご紹介します。

LangChainフレームワーク、IRIS Vector Search、LLMを使って、ユーザープロンプトからIRIS互換のSQLを生成する方法についての実験をご紹介します。

この記事は このノートブック を元にしています。 OpenExchange の このアプリケーション を使えば、すぐに使える環境で実行できます。

セットアップ

最初に必要なライブラリをインストールします。

!pip install --upgrade --quiet langchain langchain-openai langchain-iris pandas

次に、必要なモジュールをインポートし、環境をセットアップします。

import os
import datetime
import hashlib
from copy import deepcopy
from sqlalchemy import create_engine
import getpass
import pandas as pd
from langchain_core.prompts import PromptTemplate, ChatPromptTemplate
from langchain_core.example_selectors import SemanticSimilarityExampleSelector
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain.docstore.document import Document
from langchain_community.document_loaders import DataFrameLoader
from langchain.text_splitter import CharacterTextSplitter
from langchain_core.output_parsers import StrOutputParser
from langchain.globals import set_llm_cache
from langchain.cache import SQLiteCache
from langchain_iris import IRISVector

SQLiteCacheを使ってLLMコールをキャッシュします。

# Cache for LLM calls
set_llm_cache(SQLiteCache(database_path=".langchain.db"))

IRISデータベースへ接続するためのパラメータをセットします。

# IRIS database connection parameters
os.environ["ISC_LOCAL_SQL_HOSTNAME"] = "localhost"
os.environ["ISC_LOCAL_SQL_PORT"] = "1972"
os.environ["ISC_LOCAL_SQL_NAMESPACE"] = "IRISAPP"
os.environ["ISC_LOCAL_SQL_USER"] = "_system"
os.environ["ISC_LOCAL_SQL_PWD"] = "SYS"

OpenAI APIキーが環境変数に設定されていない場合は、ユーザ入力が求められます。

if not "OPENAI_API_KEY" in os.environ:
    os.environ["OPENAI_API_KEY"] = getpass.getpass()

IRISデータベースの接続文字列を作成します。

# IRIS database connection string
args = {
    'hostname': os.getenv("ISC_LOCAL_SQL_HOSTNAME"), 
    'port': os.getenv("ISC_LOCAL_SQL_PORT"), 
    'namespace': os.getenv("ISC_LOCAL_SQL_NAMESPACE"), 
    'username': os.getenv("ISC_LOCAL_SQL_USER"), 
    'password': os.getenv("ISC_LOCAL_SQL_PWD")
}
iris_conn_str = f"iris://{args['username']}:{args['password']}@{args['hostname']}:{args['port']}/{args['namespace']}"

IRISデータベースとの接続を確立します。

# Connection to IRIS database
engine = create_engine(iris_conn_str)
cnx = engine.connect().connection

システムプロンプトのコンテキスト情報を保持するdictionaryを用意します。

# Dict for context information for system prompt
context = {}
context["top_k"] = 3

プロンプトの作成

ユーザー入力をIRISデータベースと互換性のあるSQLクエリに変換するために、言語モデル用の効果的なプロンプトを作成する必要があります。

SQLクエリを生成するための基本的な指示を提供する初期プロンプトから始めます。

このテンプレートはLangChain's default prompts for MSSQL から派生し、IRISデータベース用にカスタマイズされています。

# Basic prompt template with IRIS database SQL instructions
iris_sql_template = """
You are an InterSystems IRIS expert. Given an input question, first create a syntactically correct InterSystems IRIS query to run and return the answer to the input question.
Unless the user specifies in the question a specific number of examples to obtain, query for at most {top_k} results using the TOP clause as per InterSystems IRIS. You can order the results to return the most informative data in the database.
Never query for all columns from a table. You must query only the columns that are needed to answer the question. Wrap each column name in single quotes ('') to denote them as delimited identifiers.
Pay attention to use only the column names you can see in the tables below. Be careful to not query for columns that do not exist. Also, pay attention to which column is in which table.
Pay attention to use CAST(CURRENT_DATE as date) function to get the current date, if the question involves "today".
Use double quotes to delimit columns identifiers.
Return just plain SQL; don't apply any kind of formatting.
"""

次のような文章をテンプレートに設定しています：　あなたは InterSystems IRIS のエキスパートです。 入力された質問に対して、まず、構文的に正しい InterSystems IRIS クエリを作成し、そのクエリを実行し て、入力された質問に対する回答を返します。 ユーザが質問で特定の数の例を取得するように指定しない限り、InterSystems IRIS に従って、TOP 節を使用して最大 {top_k} の結果をクエリします。 テーブルのすべての列に対してクエリを実行してはなりません。 質問に答えるために必要なカラムのみを問い合わせなければなりません。 各カラム名をシングルクォート（''）で囲み、区切り識別子にします。 以下の表で確認できるカラム名のみを使用するように注意してください。 存在しないカラムを問い合わせないように注意してください。 また、どのカラムがどのテーブルにあるかに注意すること。 質問内容が "今日 "を含む場合は、CAST(CURRENT_DATE as date)関数を使用して現在の日付を取得することに注意すること。 カラムの識別子を区切るには二重引用符を使用すること。 単なるSQLを返すこと。いかなるフォーマットも適用しないこと。

この基本プロンプトは、言語モデル(LLM)がIRISデータベースに対する特定のガイダンスを持つSQLエキスパートとして機能するように設定しています。

次に、ハルシネーション（幻覚）を避けるために、データベーススキーマに関する情報を補助プロンプトとして提供します。

# SQL template extension for including tables context information
tables_prompt_template = """
Only use the following tables:
{table_info}
"""

LLMの回答の精度を高めるために、私たちはfew-shot プロンプトと呼ばれるテクニックを使いました。 これはLLMにいくつかの例を提示するものです。

# SQL template extension for including few shots
prompt_sql_few_shots_template = """
Below are a number of examples of questions and their corresponding SQL queries.

{examples_value}
"""

私たちは few-shot の例のためにテンプレートを以下のように定義しています。

# Few shots prompt template
example_prompt_template = "User input: {input}\nSQL query: {query}"
example_prompt = PromptTemplate.from_template(example_prompt_template)

私たちは、 few-shot テンプレートを使ってユーザー・プロンプトを作っています。

# User prompt template
user_prompt = "\n" + example_prompt.invoke({"input": "{input}", "query": ""}).to_string()

最後に、すべてのプロンプトを組み合わせて最終的なプロンプトを作成します。

# Complete prompt template
prompt = (
    ChatPromptTemplate.from_messages([("system", iris_sql_template)])
    + ChatPromptTemplate.from_messages([("system", tables_prompt_template)])
    + ChatPromptTemplate.from_messages([("system", prompt_sql_few_shots_template)])
    + ChatPromptTemplate.from_messages([("human", user_prompt)])
)
prompt

このプロンプトは、変数 examples_value, input, table_info, and top_k を想定しています。

プロンプトの構成は以下の通りです。

ChatPromptTemplate(
    input_variables=['examples_value', 'input', 'table_info', 'top_k'], 
    messages=[
        SystemMessagePromptTemplate(
            prompt=PromptTemplate(
                input_variables=['top_k'], 
                template=iris_sql_template
            )
        ), 
        SystemMessagePromptTemplate(
            prompt=PromptTemplate(
                input_variables=['table_info'], 
                template=tables_prompt_template
            )
        ), 
        SystemMessagePromptTemplate(
            prompt=PromptTemplate(
                input_variables=['examples_value'], 
                template=prompt_sql_few_shots_template
            )
        ), 
        HumanMessagePromptTemplate(
            prompt=PromptTemplate(
                input_variables=['input'], 
                template=user_prompt
            )
        )
    ]
)

プロンプトがどのようにLLMに送られるかを視覚化するために、必要な変数にプレースホルダーの値を使うことができます。

prompt_value = prompt.invoke({
    "top_k": "<top_k>",
    "table_info": "<table_info>",
    "examples_value": "<examples_value>",
    "input": "<input>"
})
print(prompt_value.to_string())

System: 
You are an InterSystems IRIS expert. Given an input question, first create a syntactically correct InterSystems IRIS query to run and return the answer to the input question.
Unless the user specifies in the question a specific number of examples to obtain, query for at most <top_k> results using the TOP clause as per InterSystems IRIS. You can order the results to return the most informative data in the database.
Never query for all columns from a table. You must query only the columns that are needed to answer the question. Wrap each column name in single quotes ('') to denote them as delimited identifiers.
Pay attention to use only the column names you can see in the tables below. Be careful to not query for columns that do not exist. Also, pay attention to which column is in which table.
Pay attention to use CAST(CURRENT_DATE as date) function to get the current date, if the question involves "today".
Use double quotes to delimit columns identifiers.
Return just plain SQL; don't apply any kind of formatting.

System: 
Only use the following tables:
<table_info>

System: 
Below are a number of examples of questions and their corresponding SQL queries.

<examples_value>

Human: 
User input: <input>
SQL query: 

これで、必要な変数を与えることで、このプロンプトをLLMに送る準備ができました。 準備ができたら次のステップに進みましょう。

テーブル情報の提供

正確なSQLクエリを作成するためには、言語モデル（LLM）にデータベース・テーブルに関する詳細な情報を提供する必要があります。

この情報がないと、LLMは一見もっともらしく見えますが、ハルシネーション（幻覚）により正しくないクエリを生成する可能性があります。 そこで、最初のステップとして、IRISデータベースからテーブル定義を取得する関数を作成します。

テーブル定義情報を取得する関数

以下の関数はINFORMATION_SCHEMAに問い合わせ、指定されたスキーマのテーブル定義を取得します。

特定のテーブルが指定された場合は、そのテーブルの定義を取得します。そうでない場合は、スキーマ内の全てのテーブルの定義を取得します。

def get_table_definitions_array(cnx, schema, table=None):
    cursor = cnx.cursor()

    # Base query to get columns information
    query = """
    SELECT TABLE_SCHEMA, TABLE_NAME, COLUMN_NAME, DATA_TYPE, IS_NULLABLE, COLUMN_DEFAULT, PRIMARY_KEY, null EXTRA
    FROM INFORMATION_SCHEMA.COLUMNS
    WHERE TABLE_SCHEMA = %s
    """
    
    # Parameters for the query
    params = [schema]

    # Adding optional filters
    if table:
        query += " AND TABLE_NAME = %s"
        params.append(table)
    
    # Execute the query
    cursor.execute(query, params)

    # Fetch the results
    rows = cursor.fetchall()
    
    # Process the results to generate the table definition(s)
    table_definitions = {}
    for row in rows:
        table_schema, table_name, column_name, column_type, is_nullable, column_default, column_key, extra = row
        if table_name not in table_definitions:
            table_definitions[table_name] = []
        table_definitions[table_name].append({
            "column_name": column_name,
            "column_type": column_type,
            "is_nullable": is_nullable,
            "column_default": column_default,
            "column_key": column_key,
            "extra": extra
        })

    primary_keys = {}
    
    # Build the output string
    result = []
    for table_name, columns in table_definitions.items():
        table_def = f"CREATE TABLE {schema}.{table_name} (\n"
        column_definitions = []
        for column in columns:
            column_def = f"  {column['column_name']} {column['column_type']}"
            if column['is_nullable'] == "NO":
                column_def += " NOT NULL"
            if column['column_default'] is not None:
                column_def += f" DEFAULT {column['column_default']}"
            if column['extra']:
                column_def += f" {column['extra']}"
            column_definitions.append(column_def)
        if table_name in primary_keys:
            pk_def = f"  PRIMARY KEY ({', '.join(primary_keys[table_name])})"
            column_definitions.append(pk_def)
        table_def += ",\n".join(column_definitions)
        table_def += "\n);"
        result.append(table_def)

    return result

スキーマのテーブル定義を取得する

この例では、Aviationスキーマを使用しています。Aviationスキーマ情報一式については こちら から入手できます。

# Retrieve table definitions for the Aviation schema
tables = get_table_definitions_array(cnx, "Aviation")
print(tables)

この関数は、Aviation スキーマ内のすべてのテーブルの CREATE TABLE ステートメントを返します。

[
    'CREATE TABLE Aviation.Aircraft (\n  Event bigint NOT NULL,\n  ID varchar NOT NULL,\n  AccidentExplosion varchar,\n  AccidentFire varchar,\n  AirFrameHours varchar,\n  AirFrameHoursSince varchar,\n  AirFrameHoursSinceLastInspection varchar,\n  AircraftCategory varchar,\n  AircraftCertMaxGrossWeight integer,\n  AircraftHomeBuilt varchar,\n  AircraftKey integer NOT NULL,\n  AircraftManufacturer varchar,\n  AircraftModel varchar,\n  AircraftRegistrationClass varchar,\n  AircraftSerialNo varchar,\n  AircraftSeries varchar,\n  Damage varchar,\n  DepartureAirportId varchar,\n  DepartureCity varchar,\n  DepartureCountry varchar,\n  DepartureSameAsEvent varchar,\n  DepartureState varchar,\n  DepartureTime integer,\n  DepartureTimeZone varchar,\n  DestinationAirportId varchar,\n  DestinationCity varchar,\n  DestinationCountry varchar,\n  DestinationSameAsLocal varchar,\n  DestinationState varchar,\n  EngineCount integer,\n  EvacuationOccurred varchar,\n  EventId varchar NOT NULL,\n  FlightMedical varchar,\n  FlightMedicalType varchar,\n  FlightPhase integer,\n  FlightPlan varchar,\n  FlightPlanActivated varchar,\n  FlightSiteSeeing varchar,\n  FlightType varchar,\n  GearType varchar,\n  LastInspectionDate timestamp,\n  LastInspectionType varchar,\n  Missing varchar,\n  OperationDomestic varchar,\n  OperationScheduled varchar,\n  OperationType varchar,\n  OperatorCertificate varchar,\n  OperatorCertificateNum varchar,\n  OperatorCode varchar,\n  OperatorCountry varchar,\n  OperatorIndividual varchar,\n  OperatorName varchar,\n  OperatorState varchar,\n  Owner varchar,\n  OwnerCertified varchar,\n  OwnerCountry varchar,\n  OwnerState varchar,\n  RegistrationNumber varchar,\n  ReportedToICAO varchar,\n  SeatsCabinCrew integer,\n  SeatsFlightCrew integer,\n  SeatsPassengers integer,\n  SeatsTotal integer,\n  SecondPilot varchar,\n  childsub bigint NOT NULL DEFAULT $i(^Aviation.EventC("Aircraft"))\n);',
    'CREATE TABLE Aviation.Crew (\n  Aircraft varchar NOT NULL,\n  ID varchar NOT NULL,\n  Age integer,\n  AircraftKey integer NOT NULL,\n  Category varchar,\n  CrewNumber integer NOT NULL,\n  EventId varchar NOT NULL,\n  Injury varchar,\n  MedicalCertification varchar,\n  MedicalCertificationDate timestamp,\n  MedicalCertificationValid varchar,\n  Seat varchar,\n  SeatbeltUsed varchar,\n  Sex varchar,\n  ShoulderHarnessUsed varchar,\n  ToxicologyTestPerformed varchar,\n  childsub bigint NOT NULL DEFAULT $i(^Aviation.AircraftC("Crew"))\n);',
    'CREATE TABLE Aviation.Event (\n  ID bigint NOT NULL DEFAULT $i(^Aviation.EventD),\n  AirportDirection integer,\n  AirportDistance varchar,\n  AirportElevation integer,\n  AirportLocation varchar,\n  AirportName varchar,\n  Altimeter varchar,\n  EventDate timestamp,\n  EventId varchar NOT NULL,\n  EventTime integer,\n  FAADistrictOffice varchar,\n  InjuriesGroundFatal integer,\n  InjuriesGroundMinor integer,\n  InjuriesGroundSerious integer,\n  InjuriesHighest varchar,\n  InjuriesTotal integer,\n  InjuriesTotalFatal integer,\n  InjuriesTotalMinor integer,\n  InjuriesTotalNone integer,\n  InjuriesTotalSerious integer,\n  InvestigatingAgency varchar,\n  LightConditions varchar,\n  LocationCity varchar,\n  LocationCoordsLatitude double,\n  LocationCoordsLongitude double,\n  LocationCountry varchar,\n  LocationSiteZipCode varchar,\n  LocationState varchar,\n  MidAir varchar,\n  NTSBId varchar,\n  NarrativeCause varchar,\n  NarrativeFull varchar,\n  NarrativeSummary varchar,\n  OnGroundCollision varchar,\n  SkyConditionCeiling varchar,\n  SkyConditionCeilingHeight integer,\n  SkyConditionNonCeiling varchar,\n  SkyConditionNonCeilingHeight integer,\n  TimeZone varchar,\n  Type varchar,\n  Visibility varchar,\n  WeatherAirTemperature integer,\n  WeatherPrecipitation varchar,\n  WindDirection integer,\n  WindDirectionIndicator varchar,\n  WindGust integer,\n  WindGustIndicator varchar,\n  WindVelocity integer,\n  WindVelocityIndicator varchar\n);'
]

これらのテーブル定義ができたので、次のステップに進むことができます。

これにより、LLMがSQLクエリを生成する際に、データベース・スキーマに関する正確で包括的な情報が得られるようになります。

最も関連性の高いテーブルを選ぶ

データベース、特に大規模なデータベースを扱う場合、プロンプト内のすべてのテーブルのデータ定義言語（DDL）を送信することは非現実的です。

このアプローチは小規模なデータベースでは有効かもしれませんが、現実のデータベースには数百から数千のテーブルが含まれていることが多く、すべてのテーブルを処理するのは非効率的です。

さらに、SQLクエリを効率的に生成するために、言語モデルがデータベース内のすべてのテーブルを認識する必要があるとは考えにくいです。 この課題に対処するため、セマンティック検索機能を活用し、ユーザーのクエリに基づいて最も関連性の高いテーブルのみを選択することができます。

アプローチ

IRIS Vector Searchでセマンティック検索を使用することでこれを実現します。

この方法は、SQL要素の識別子（テーブル、フィールド、キーなど）に意味のある名前がある場合に最も効果的です。識別子が任意のコードである場合は、代わりにデータ dictionaryの使用を検討してください。

手順

1. テーブル情報の取得

まず、テーブル定義をpandas DataFrameに取り出します。

# Retrieve table definitions into a pandas DataFrame
table_def = get_table_definitions_array(cnx=cnx, schema='Aviation')
table_df = pd.DataFrame(data=table_def, columns=["col_def"])
table_df["id"] = table_df.index + 1
table_df

DataFrame（table_df）は以下のようになります。

2. 定義をDocumentsに分割する

次に、テーブル定義をLangchain Documentsに分割します。 このステップは、大きなテキストの塊を扱い、テキスト埋め込みを抽出するために非常に重要です。

loader = DataFrameLoader(table_df, page_content_column="col_def")
documents = loader.load()
text_splitter = CharacterTextSplitter(chunk_size=400, chunk_overlap=20, separator="\n")
tables_docs = text_splitter.split_documents(documents)
tables_docs

その結果、tables_docsリストには、次のようにメタデータ付きの分割ドキュメントが含まれます。

[Document(metadata={'id': 1}, page_content='CREATE TABLE Aviation.Aircraft (\n  Event bigint NOT NULL,\n  ID varchar NOT NULL,\n  ...'),
 Document(metadata={'id': 2}, page_content='CREATE TABLE Aviation.Crew (\n  Aircraft varchar NOT NULL,\n  ID varchar NOT NULL,\n  ...'),
 Document(metadata={'id': 3}, page_content='CREATE TABLE Aviation.Event (\n  ID bigint NOT NULL DEFAULT $i(^Aviation.EventD),\n  ...')]

3. 埋め込み(Embedding)の抽出とIRISへの保存

次に，langchain-irisのIRISVectorクラスを使って埋め込みベクトルを抽出し、それをIRISに格納します。

tables_vector_store = IRISVector.from_documents(
    embedding=OpenAIEmbeddings(), 
    documents=tables_docs,
    connection_string=iris_conn_str,
    collection_name="sql_tables",
    pre_delete_collection=True
)

注意: pre_delete_collection フラグは、各テスト実行で新鮮なコレクションを確保するために、デモ用に True に設定されています。 本番環境では、このフラグは通常 False に設定します。

4. 関連文書の検索

テーブルに埋め込み(Embedding)が保存されたことで、ユーザー入力に基づいて関連するテーブルを検索できるようになりました。

input_query = "List the first 2 manufacturers"
relevant_tables_docs = tables_vector_store.similarity_search(input_query, k=3)
relevant_tables_docs

例えば、manufacturers を検索すると、次のような結果が返ってきます。

[Document(metadata={'id': 1}, page_content='GearType varchar,\n  LastInspectionDate timestamp,\n  ...'),
 Document(metadata={'id': 1}, page_content='AircraftModel varchar,\n  AircraftRegistrationClass varchar,\n  ...'),
 Document(metadata={'id': 3}, page_content='LocationSiteZipCode varchar,\n  LocationState varchar,\n  ...')]

メタデータから、テーブルID 1 (Aviation.Aircraft)だけが関連性があり、クエリと一致していることがわかります。

5. エッジケースへの対応

このアプローチは一般的に効果的ではありますが、常に完璧とは限りません。 たとえば、事故現場のクエリを実行すると、関連性の低いテーブルが返されることもあります。

input_query = "List the top 10 most crash sites"
relevant_tables_docs = tables_vector_store.similarity_search(input_query, k=3)
relevant_tables_docs

結果は以下の通りです。

[Document(metadata={'id': 3}, page_content='LocationSiteZipCode varchar,\n  LocationState varchar,\n  ...'),
 Document(metadata={'id': 3}, page_content='InjuriesGroundSerious integer,\n  InjuriesHighest varchar,\n  ...'),
 Document(metadata={'id': 1}, page_content='CREATE TABLE Aviation.Aircraft (\n  Event bigint NOT NULL,\n  ID varchar NOT NULL,\n  ...')]

正しいAviation.Eventテーブルを2回取得したにもかかわらず、Aviation.Aircraftテーブルも表示されることがあります。これは、この例の範囲を超えているため、将来の実装に委ねられます。

6. 関連テーブルを取得する関数を定義する

このプロセスを自動化するため、ユーザー入力に基づいて関連するテーブルをフィルタリングして返す関数を定義します。

def get_relevant_tables(user_input, tables_vector_store, table_df):
    relevant_tables_docs = tables_vector_store.similarity_search(user_input)
    relevant_tables_docs_indices = [x.metadata["id"] for x in relevant_tables_docs]
    indices = table_df["id"].isin(relevant_tables_docs_indices)
    relevant_tables_array = [x for x in table_df[indices]["col_def"]]
    return relevant_tables_array

この機能は、LLMに送信する関連テーブルのみを効率的に検索し、プロンプトの長さを短縮し、クエリ全体のパフォーマンスを向上させるのに役立ちます。

最も適切な例を選ぶ（Few-Shotプロンプティング）

言語モデル(LLM)を扱うとき、適切な例を提供することは、正確で文脈的に適切な応答を保証するのに役立ちます。

これらの例は "Few-Shot" 例と呼ばれ、LLMが処理すべきクエリの構造とコンテキストを理解するためのガイドとなります。今回のケースでは、IRISのSQL構文とデータベースで使用可能なテーブルを幅広くカバーする多様なSQLクエリを examples_value 変数に入力する必要があります。これは、LLMが正しくないクエリーや無関係なクエリーを生成するのを防ぐのに役立ちます。

クエリ例の定義

以下は、様々なSQL操作を説明するために作られたクエリ例のリストです。

examples = [
    {"input": "List all aircrafts.", "query": "SELECT * FROM Aviation.Aircraft"},
    {"input": "Find all incidents for the aircraft with ID 'N12345'.", "query": "SELECT * FROM Aviation.Event WHERE EventId IN (SELECT EventId FROM Aviation.Aircraft WHERE ID = 'N12345')"},
    {"input": "List all incidents in the 'Commercial' operation type.", "query": "SELECT * FROM Aviation.Event WHERE EventId IN (SELECT EventId FROM Aviation.Aircraft WHERE OperationType = 'Commercial')"},
    {"input": "Find the total number of incidents.", "query": "SELECT COUNT(*) FROM Aviation.Event"},
    {"input": "List all incidents that occurred in 'Canada'.", "query": "SELECT * FROM Aviation.Event WHERE LocationCountry = 'Canada'"},
    {"input": "How many incidents are associated with the aircraft with AircraftKey 5?", "query": "SELECT COUNT(*) FROM Aviation.Aircraft WHERE AircraftKey = 5"},
    {"input": "Find the total number of distinct aircrafts involved in incidents.", "query": "SELECT COUNT(DISTINCT AircraftKey) FROM Aviation.Aircraft"},
    {"input": "List all incidents that occurred after 5 PM.", "query": "SELECT * FROM Aviation.Event WHERE EventTime > 1700"},
    {"input": "Who are the top 5 operators by the number of incidents?", "query": "SELECT TOP 5 OperatorName, COUNT(*) AS IncidentCount FROM Aviation.Aircraft GROUP BY OperatorName ORDER BY IncidentCount DESC"},
    {"input": "Which incidents occurred in the year 2020?", "query": "SELECT * FROM Aviation.Event WHERE YEAR(EventDate) = '2020'"},
    {"input": "What was the month with most events in the year 2020?", "query": "SELECT TOP 1 MONTH(EventDate) EventMonth, COUNT(*) EventCount FROM Aviation.Event WHERE YEAR(EventDate) = '2020' GROUP BY MONTH(EventDate) ORDER BY EventCount DESC"},
    {"input": "How many crew members were involved in incidents?", "query": "SELECT COUNT(*) FROM Aviation.Crew"},
    {"input": "List all incidents with detailed aircraft information for incidents that occurred in the year 2012.", "query": "SELECT e.EventId, e.EventDate, a.AircraftManufacturer, a.AircraftModel, a.AircraftCategory FROM Aviation.Event e JOIN Aviation.Aircraft a ON e.EventId = a.EventId WHERE Year(e.EventDate) = 2012"},
    {"input": "Find all incidents where there were more than 5 injuries and include the aircraft manufacturer and model.", "query": "SELECT e.EventId, e.InjuriesTotal, a.AircraftManufacturer, a.AircraftModel FROM Aviation.Event e JOIN Aviation.Aircraft a ON e.EventId = a.EventId WHERE e.InjuriesTotal > 5"},
    {"input": "List all crew members involved in incidents with serious injuries, along with the incident date and location.", "query": "SELECT c.CrewNumber AS 'Crew Number', c.Age, c.Sex AS Gender, e.EventDate AS 'Event Date', e.LocationCity AS 'Location City', e.LocationState AS 'Location State' FROM Aviation.Crew c JOIN Aviation.Event e ON c.EventId = e.EventId WHERE c.Injury = 'Serious'"}
]

関連する事例の選択

例のリストが増え続けることを考えると、LLMにすべての例を提供することは現実的ではありません。代わりに、IRIS Vector SearchとSemanticSimilarityExampleSelectorクラスを使用して、ユーザーのプロンプトに基づいて最も関連性の高い例を特定します。

Example Selector を定義する

example_selector = SemanticSimilarityExampleSelector.from_examples(
    examples,
    OpenAIEmbeddings(),
    IRISVector,
    k=5,
    input_keys=["input"],
    connection_string=iris_conn_str,
    collection_name="sql_samples",
    pre_delete_collection=True
)

注意: pre_delete_collection フラグは、各テスト実行で新鮮なコレクションを確保するためのデモンストレーション目的で使用されています。本番環境では、不要な削除を避けるためにこのフラグを False に設定する必要があります。

Selectorに問い合わせる

与えられた入力に最も関連する例を見つけるには、次のようにSelector を使用します。

input_query = "Find all events in 2010 informing the Event Id and date, location city and state, aircraft manufacturer and model."
relevant_examples = example_selector.select_examples({"input": input_query})

結果は以下のようになります。

[{'input': 'List all incidents with detailed aircraft information for incidents that occurred in the year 2012.', 'query': 'SELECT e.EventId, e.EventDate, a.AircraftManufacturer, a.AircraftModel, a.AircraftCategory FROM Aviation.Event e JOIN Aviation.Aircraft a ON e.EventId = a.EventId WHERE Year(e.EventDate) = 2012'},
 {'input': "Find all incidents for the aircraft with ID 'N12345'.", 'query': "SELECT * FROM Aviation.Event WHERE EventId IN (SELECT EventId FROM Aviation.Aircraft WHERE ID = 'N12345')"},
 {'input': 'Find all incidents where there were more than 5 injuries and include the aircraft manufacturer and model.', 'query': 'SELECT e.EventId, e.InjuriesTotal, a.AircraftManufacturer, a.AircraftModel FROM Aviation.Event e JOIN Aviation.Aircraft a ON e.EventId = a.EventId WHERE e.InjuriesTotal > 5'},
 {'input': 'List all aircrafts.', 'query': 'SELECT * FROM Aviation.Aircraft'},
 {'input': 'Find the total number of distinct aircrafts involved in incidents.', 'query': 'SELECT COUNT(DISTINCT AircraftKey) FROM Aviation.Aircraft'}]

数量に関連した例が特に必要な場合は、それに応じてSelectorに問い合わせることができます。

input_query = "What is the number of incidents involving Boeing aircraft."
quantity_examples = example_selector.select_examples({"input": input_query})

出力は以下の通りです。

[{'input': 'How many incidents are associated with the aircraft with AircraftKey 5?', 'query': 'SELECT COUNT(*) FROM Aviation.Aircraft WHERE AircraftKey = 5'},
 {'input': 'Find the total number of distinct aircrafts involved in incidents.', 'query': 'SELECT COUNT(DISTINCT AircraftKey) FROM Aviation.Aircraft'},
 {'input': 'How many crew members were involved in incidents?', 'query': 'SELECT COUNT(*) FROM Aviation.Crew'},
 {'input': 'Find all incidents where there were more than 5 injuries and include the aircraft manufacturer and model.', 'query': 'SELECT e.EventId, e.InjuriesTotal, a.AircraftManufacturer, a.AircraftModel FROM Aviation.Event e JOIN Aviation.Aircraft a ON e.EventId = a.EventId WHERE e.InjuriesTotal > 5'},
 {'input': 'List all incidents with detailed aircraft information for incidents that occurred in the year 2012.', 'query': 'SELECT e.EventId, e.EventDate, a.AircraftManufacturer, a.AircraftModel, a.AircraftCategory FROM Aviation.Event e JOIN Aviation.Aircraft a ON e.EventId = a.EventId WHERE Year(e.EventDate) = 2012'}]

この出力には、特にカウントと量を扱った例が含まれています。

今後の検討事項

SemanticSimilarityExampleSelectorは強力ですが、選択された例がすべて完璧であるとは限らないことに注意することが重要です。

将来的な改良には、フィルターやしきい値を追加して関連性の低い結果を除外し、最も適切な例だけがLLMに提供されるようにすることが含まれるかもしれません。

精度テスト

プロンプトとSQLクエリ生成のパフォーマンスを評価するために、一連のテストを設定し実行する必要があります。その目的は、LLMがユーザーの入力に基づいてSQLクエリを生成する際に、例題に基づいたfew shotを使用する場合と使用しない場合の、その精度を評価することである。

SQLクエリを生成する関数

まず、LLMを使って、提供されたコンテキスト、プロンプト、ユーザー入力、その他のパラメーターに基づいてSQLクエリーを生成する関数を定義します。

def get_sql_from_text(context, prompt, user_input, use_few_shots, tables_vector_store, table_df, example_selector=None, example_prompt=None):
    relevant_tables = get_relevant_tables(user_input, tables_vector_store, table_df)
    context["table_info"] = "\n\n".join(relevant_tables)

    examples = example_selector.select_examples({"input": user_input}) if example_selector else []
    context["examples_value"] = "\n\n".join([
        example_prompt.invoke(x).to_string() for x in examples
    ])
    
    model = ChatOpenAI(model="gpt-3.5-turbo", temperature=0)
    output_parser = StrOutputParser()
    chain_model = prompt | model | output_parser
    
    response = chain_model.invoke({
        "top_k": context["top_k"],
        "table_info": context["table_info"],
        "examples_value": context["examples_value"],
        "input": user_input
    })
    return response

プロンプトの実行

例文がある場合とない場合のプロンプトをテストします。

# Prompt execution **with** few shots
input = "Find all events in 2010 informing the Event Id and date, location city and state, aircraft manufacturer and model."
response_with_few_shots = get_sql_from_text(
    context, 
    prompt, 
    user_input=input, 
    use_few_shots=True, 
    tables_vector_store=tables_vector_store, 
    table_df=table_df,
    example_selector=example_selector, 
    example_prompt=example_prompt,
)
print(response_with_few_shots)

SELECT e.EventId, e.EventDate, e.LocationCity, e.LocationState, a.AircraftManufacturer, a.AircraftModel
FROM Aviation.Event e
JOIN Aviation.Aircraft a ON e.EventId = a.EventId
WHERE Year(e.EventDate) = 2010

# Prompt execution **without** few shots
input = "Find all events in 2010 informing the Event Id and date, location city and state, aircraft manufacturer and model."
response_with_no_few_shots = get_sql_from_text(
    context, 
    prompt, 
    user_input=input, 
    use_few_shots=False, 
    tables_vector_store=tables_vector_store, 
    table_df=table_df,
)
print(response_with_no_few_shots)

SELECT TOP 3 "EventId", "EventDate", "LocationCity", "LocationState", "AircraftManufacturer", "AircraftModel"
FROM Aviation.Event e
JOIN Aviation.Aircraft a ON e.ID = a.Event
WHERE e.EventDate >= '2010-01-01' AND e.EventDate < '2011-01-01'
Utility Functions for Testing

生成されたSQLクエリをテストするために、いくつかのユーティリティ関数を定義します。

def execute_sql_query(cnx, query):
    try:
        cursor = cnx.cursor()
        cursor.execute(query)
        rows = cursor.fetchall()
        return rows
    except:
        print('Error running query:')
        print(query)
        print('-'*80)
    return None

def sql_result_equals(cnx, query, expected):
    rows = execute_sql_query(cnx, query)
    result = [set(row._asdict().values()) for row in rows or []]
    if result != expected and rows is not None:
        print('Result not as expected for query:')
        print(query)
        print('-'*80)
    return result == expected

# SQL test for prompt **with** few shots
print("SQL is OK" if not execute_sql_query(cnx, response_with_few_shots) is None else "SQL is not OK")

    SQL is OK

# SQL test for prompt **without** few shots
print("SQL is OK" if not execute_sql_query(cnx, response_with_no_few_shots) is None else "SQL is not OK")

    error on running query: 
    SELECT TOP 3 "EventId", "EventDate", "LocationCity", "LocationState", "AircraftManufacturer", "AircraftModel"
    FROM Aviation.Event e
    JOIN Aviation.Aircraft a ON e.ID = a.Event
    WHERE e.EventDate >= '2010-01-01' AND e.EventDate < '2011-01-01'
    --------------------------------------------------------------------------------
    SQL is not OK

テストの定義と実行

一連のテストケースを定義し、実行します。

tests = [{
    "input": "What were the top 3 years with the most recorded events?",
    "expected": [{128, 2003}, {122, 2007}, {117, 2005}]
},{
    "input": "How many incidents involving Boeing aircraft.",
    "expected": [{5}]
},{
    "input": "How many incidents that resulted in fatalities.",
    "expected": [{237}]
},{
    "input": "List event Id and date and, crew number, age and gender for incidents that occurred in 2013.",
    "expected": [{1, datetime.datetime(2013, 3, 4, 11, 6), '20130305X71252', 59, 'M'},
                 {1, datetime.datetime(2013, 1, 1, 15, 0), '20130101X94035', 32, 'M'},
                 {2, datetime.datetime(2013, 1, 1, 15, 0), '20130101X94035', 35, 'M'},
                 {1, datetime.datetime(2013, 1, 12, 15, 0), '20130113X42535', 25, 'M'},
                 {2, datetime.datetime(2013, 1, 12, 15, 0), '20130113X42535', 34, 'M'},
                 {1, datetime.datetime(2013, 2, 1, 15, 0), '20130203X53401', 29, 'M'},
                 {1, datetime.datetime(2013, 2, 15, 15, 0), '20130218X70747', 27, 'M'},
                 {1, datetime.datetime(2013, 3, 2, 15, 0), '20130303X21011', 49, 'M'},
                 {1, datetime.datetime(2013, 3, 23, 13, 52), '20130326X85150', 'M', None}]
},{
    "input": "Find the total number of incidents that occurred in the United States.",
    "expected": [{1178}]
},{
    "input": "List all incidents latitude and longitude coordinates with more than 5 injuries that occurred in 2010.",
    "expected": [{-78.76833333333333, 43.25277777777778}]
},{
    "input": "Find all incidents in 2010 informing the Event Id and date, location city and state, aircraft manufacturer and model.",
    "expected": [
        {datetime.datetime(2010, 5, 20, 13, 43), '20100520X60222', 'CIRRUS DESIGN CORP', 'Farmingdale', 'New York', 'SR22'},
        {datetime.datetime(2010, 4, 11, 15, 0), '20100411X73253', 'CZECH AIRCRAFT WORKS SPOL SRO', 'Millbrook', 'New York', 'SPORTCRUISER'},
        {'108', datetime.datetime(2010, 1, 9, 12, 55), '20100111X41106', 'Bayport', 'New York', 'STINSON'},
        {datetime.datetime(2010, 8, 1, 14, 20), '20100801X85218', 'A185F', 'CESSNA', 'New York', 'Newfane'}
    ]
}]

精度評価

テストを実施し、精度を計算します。

def execute_tests(cnx, context, prompt, use_few_shots, tables_vector_store, table_df, example_selector, example_prompt):
    tests_generated_sql = [(x, get_sql_from_text(
            context, 
            prompt, 
            user_input=x['input'], 
            use_few_shots=use_few_shots, 
            tables_vector_store=tables_vector_store, 
            table_df=table_df,
            example_selector=example_selector if use_few_shots else None, 
            example_prompt=example_prompt if use_few_shots else None,
        )) for x in deepcopy(tests)]
    
    tests_sql_executions = [(x[0], sql_result_equals(cnx, x[1], x[0]['expected'])) 
                            for x in tests_generated_sql]
    
    accuracy = sum(1 for i in tests_sql_executions if i[1] == True) / len(tests_sql_executions)
    print(f'Accuracy: {accuracy}')
    print('-'*80)

結果

# Accuracy tests for prompts executed **without** few shots
use_few_shots = False
execute_tests(
    cnx,
    context, 
    prompt, 
    use_few_shots, 
    tables_vector_store, 
    table_df, 
    example_selector, 
    example_prompt
)

    error on running query: 
    SELECT "EventDate", COUNT("EventId") as "TotalEvents"
    FROM Aviation.Event
    GROUP BY "EventDate"
    ORDER BY "TotalEvents" DESC
    TOP 3;
    --------------------------------------------------------------------------------
    error on running query: 
    SELECT "EventId", "EventDate", "C"."CrewNumber", "C"."Age", "C"."Sex"
    FROM "Aviation.Event" AS "E"
    JOIN "Aviation.Crew" AS "C" ON "E"."ID" = "C"."EventId"
    WHERE "E"."EventDate" >= '2013-01-01' AND "E"."EventDate" < '2014-01-01'
    --------------------------------------------------------------------------------
    result not expected for query: 
    SELECT TOP 3 "e"."EventId", "e"."EventDate", "e"."LocationCity", "e"."LocationState", "a"."AircraftManufacturer", "a"."AircraftModel"
    FROM "Aviation"."Event" AS "e"
    JOIN "Aviation"."Aircraft" AS "a" ON "e"."ID" = "a"."Event"
    WHERE "e"."EventDate" >= '2010-01-01' AND "e"."EventDate" < '2011-01-01'
    --------------------------------------------------------------------------------
    accuracy: 0.5714285714285714
    --------------------------------------------------------------------------------

# Accuracy tests for prompts executed **with** few shots
use_few_shots = True
execute_tests(
    cnx,
    context, 
    prompt, 
    use_few_shots, 
    tables_vector_store, 
    table_df, 
    example_selector, 
    example_prompt
)

    error on running query: 
    SELECT e.EventId, e.EventDate, e.LocationCity, e.LocationState, a.AircraftManufacturer, a.AircraftModel
    FROM Aviation.Event e
    JOIN Aviation.Aircraft a ON e.EventId = a.EventId
    WHERE Year(e.EventDate) = 2010 TOP 3
    --------------------------------------------------------------------------------
    accuracy: 0.8571428571428571
    --------------------------------------------------------------------------------

結論

例（few shots）を使って生成されたSQLクエリの精度は、例なしで生成されたもの（85％対57％）に比べて約49％高くなりました。

ご参考

• https://python.langchain.com/v0.1/docs/expression_language/get_started/
• https://python.langchain.com/v0.1/docs/use_cases/sql/prompting/
• https://python.langchain.com/v0.1/docs/modules/model_io/prompts/composition/

Pandas は単に人気のあるソフトウェアライブラリだけではありません。 これは、Python データ分析環境の基礎でもあります。 その単純さとパワーで知られており、データの準備と分析の複雑さをより扱いやすい形態に変換する上で不可欠な多様なデータ構造と関数が備わっています。 これは、主要なデータ管理および分析ソリューションである InterSystems IRIS プラットフォームのフレームワーク内で、主要評価指標（KPI）やレポート作成用の ObjectScript などの特殊な環境に特に関連しています。
 
データの処理と分析の分野において、Pandas はいくつかの理由により際立っています。 この記事では、それらの側面を詳細に探ります。
 

• データ分析における Pandas の主なメリット:

ここでは、Pandas を使用する様々なメリットについて深く掘り下げます。 直感的な構文、大規模なデータセットの効率的な処理、および異なるデータ形式のシームレスな操作などが含まれます。 Pandas を既存のデータ分析ワークフローに統合する容易さも、生産性と効率を強化する大きな要因です。

• Pandas による一般的なデータ分析タスクのソリューション:

Pandas には、単純なデータ集計から複雑な変換まで、日常的なデータ分析タスクを処理できる十分な汎用性が備わっています。 こういった一般的な課題の解決に Pandas をどのように使用できるについて、データクリーニング、変換、および探索的データ分析における機能を紹介しながら説明します。 このセクションでは、Pandas によってこれらのタスクがどれほど単純化されるかに関する実用的なデータを提供します。

• IRIS の ObjectScript KPI で直接 Pandas を使用する:

IRIS プラットフォームで KPI の開発に Pandas と ObjectScript を統合すると、まさに変革がもたらされます。 ここでは、直接 ObjectScript 内で Pandas を使用して KPI 開発プロセスを強化する方法を説明します。 また、Pandas を使ってデータの分析と可視化を行い、それによってより堅牢でインサイトに満ちた KPI を得る実用的な例も探ります。

•  IRIS 分析プロセスで Pandas を実装する際の推奨事項:

既存の分析プロセスに新しいツールを実装するのは困難な場合があります。 そのため、このセクションでは、Pandas をできる限り円滑に IRIS 分析エコシステムに統合するためにベストプラクティスと推奨事項を紹介します。 セットアップと構成から最適化とベストプラクティスまで、データ分析ワークフローへの Pandas の統合を成功させるための基本的なガイドラインを説明します。
 
Pandas は、Python プログラミング言語による強力なデータ分析ライブラリです。 Pandas でデータ分析を行うことには、以下のようないくつかのメリットがあります。
 

1. 使いやすさ: Pandas にはデータ操作用の単純で直感的なインターフェースが備わっています。 NumPy ライブラリをベースに構築されており、DataFrames などの高レベルデータ構造を提供するため、表形式データを簡単に操作できます。  
2. データ構造: Pandas の主なデータ構造は Series と DataFrame です。 Series はラベル付きの一次元配列であるのに対し、DataFrame は 1 セットの Series を表現する 2 次元のテーブルです。 これらのデータ構造を組み合わせることで、データを便利に格納し、操作することができます。  
3. 欠損データの処理: Pandas には欠損データ（NaN または None）の検出と処理に使用する便利なメソッドが備わっています。 欠損データを削除、入力、または置換するメソッドがいくつか含まれるため、実際のデータの操作が単純化されます。  
4. データのグループ化と集計: Pandas では、特徴毎のデータのグループ化と各データグループへの集計関数（合計、平均、中央など）の適応を簡単に行えます。  
5. 強力なインデックス作成機能: Pandas には、データのインデックスを作成するための柔軟なツールが備わっています。 ラベル、数値インデックス、または複数のレベルのインデックス作成を使用できます。 データを効率的に絞り込み、選択、および操作することができます。  
6. データの読み取りと書き込み: Pandas では、CSV、Excel、SQL、JSON、HTML など、複数のデータ形式がサポートされています。 様々なソースのデータの読み取りやソースへの書き込みのプロセスが容易です。  
7. 広範な可視化機能: Pandas には、Matplotlib や Seaborn などの可視化ライブラリが統合されているため、特に Embedded Python 経由の統合を通じて DeepSeeWeb を使用することで、グラフの作成やデータの可視化を簡単に行えます。  
8. 効率的な時間管理: Pandas には、タイムスタンプや期間を操作するための強力なツールなど、時系列の操作に使用できる機能が複数含まれています。  
9. 広範なデータ操作機能: ライブラリには、データの絞り込み、ソート、および再構成や、テーブルの結合やマージを行うための様々な関数が備わっているため、強力なデータ操作ツールを得られます。  
10. 優れたパフォーマンス: Pandas は、大量のデータを処理できるように意図的に最適化されています。 Cython と強化されたデータ構造を使用することで、高いパフォーマンスを提供しています。

 
ObjectScript 環境で Pandas の実装例を見てみましょう。 開発環境として VSCode を使用します。 この場合の IDE は、ObjectScript 用のデバッガーとエディターを提供する InterSystems ObjectScript Extension Pack の提供状況に基づいて選択されました。
まずは、KPI クラスを作成しましょう。

  Class BI.KPI.pandasKpi Extends%DeepSee.KPI
{
}

 
次に、KPI のタイプ、名前、および列とフィルターの数を定義する XML ドキュメントを作成する必要があります。
 

XData KPI [ XMLNamespace = "http://www.intersystems.com/deepsee/kpi" ]
{
<!-- 'manual' KPI タイプは、ユーザーが定義したクラスメソッドからデータが収集されることを DeepSee に示します-->
 
<kpiname="MembersPandasDemo"sourceType="manual">
 
 <!-- この KPI クエリに必要となる列は 1 つのみです -->
 
<propertycolumnNo="1"name="Members"displayName="Community Members"/>
 
<!-- 最後に、メンバーのフィルターを定義する必要があります -->
 
<filtername="InterSystemsMember"displayName="InterSystems member"sql="SELECT DISTINCT ISCMember from Community.Member"/>
 
 </kpi>
}

 
次のステップは、Python 関数の定義、インポートの記述、および必要な変数の作成です。
 

ClassMethod MembersDF(sqlstring) As%Library.DynamicArray [ Language = python ]
{
            # First of all, we import the most important library in our script: IRIS.
            # IRIS library provides syntax for calling ObjectScript classes.
            # It simplifies Python-ObjectScript integration.
            # With the help of the library we can call any class and class method, and
            # it returns whatever data type we like, and ObjectScript understands it.
            import iris
            # Then, of course, import the pandas itself.
            import pandas as pd
            # Create three empty arrays:
            Id_list = []
            time_list = []
            ics_member = []

 
次のステップ: データベースに対するクエリを定義します。
 

# Define SQL query for fetching data.
# The query can be as simple as possible.
# All the work will be done by pandas:
            query = """
            SELECT
            id as ID, CAST(TO_CHAR(Created, 'YYYYMM') as Int) as MonthYear, ISCMember as ISC
            FROM Community.Member
            order by Created DESC
            """

次に、生成されるデータを配列グループに保存する必要があります。

# Call the class specified for executing SQL statements.
# We use embedded Python library to call the class:
sql_class = iris.sql.prepare(query)
 
# We use it again to call dedicated class methods:
rs = sql_class.execute()
 
# Then we use pandas directly on the result set to make dataFrame:
data = rs.dataframe()

            
We also can pass an argument to filter our data frame.

# フィルターの例
# We take an argument sqlstring which, in this case, contains boolean data.
# With a handy function .loc filtering all the data
sqlstring が False でない場合:
        data = data.loc[data["ISC"] == int(sqlstring)]

 
次に、データをグループ化して、その x 軸を定義する必要があります。
 
 

# Group data by date displayed like MonthYear:
grouped_data = data.groupby(["MonthYear"]).count()

残念ながら、直接グループ化されたデータ DataFrame から日付列を取得することはできないため、
代わりに元の DataFrame から日付列を取得して処理します。

# Filter out duplicate dates and append them to a list.
# After grouping by MonthYear, pandas automatically filters off duplicate dates.
# We should do the same to match our arrays:
sorted_filtered_dates = [item for item in set(data["MonthYear"])]
# Reverse the dates from left to right:
date = sorted(sorted_filtered_dates, reverse=True)
# Convert dict to a list:
id = grouped_data["ID"].id.tolist()
# Reverse values according to the date array:
id.reverse()
 
# In order to return the appropriate object to ObjectScript so that it understands it,
# we call '%Library.DynamicArray' (it is the closest one to python and an easy-to-use type of array).
# Again, we use IRIS library inside python code:
OBJIDList = iris.cls('%Library.DynamicArray')._New()
OBJtimeList = iris.cls('%Library.DynamicArray')._New()
 
# Append all data to DynamicArray class methods Push()
for i in date:
        OBJtimeList._Push(i)
for i in ID:
        OBJIDList._Push(i)
return OBJIDList, OBJtimeList
}

 
次のステップでは、DeepSee がどのデータを取得するかを理解するように KPI 固有のメソッドを定義します。
 

// メソッドを定義します。 The method must always be %OnLoadKPI(). Otherwise, the system will not recognise it.
 
Method %OnLoadKPI() As%Status
{
 
 //Define string for the filter. Set the default to zero
 set sqlstring = 0
    //Call %filterValues method to fetch any filter data from the widget.
    if$IsObject(..%filterValues) {
        if (..%filterValues.InterSystemsMember'="")
        {
            set sqlstring=..%filterValues.%data("InterSystemsMember")
        }
    }
    //Call pandas function, pass filter value if any, and receive dynamic arrays with data.
    set sqlValue = ..MembersDF(sqlstring)
 
    //Assign each tuple to a variable.
    set idList = sqlValue.GetAt(1)
    set timeList = sqlValue.GetAt(2)
  
    //Calculate size of x-axis. It will be rows for our widget:
    set rowCount = timeList.%Size()
 
    //Since we need only one column, we assign variable to 1:
    set colCount = 1
    set ..%seriesCount=rowCount
  
    //Now, for each row, assign time value and ID value of our members:
    for rows = 1:1:..%seriesCount
    {
        set ..%seriesNames(rows)=timeList.%Get(rows-1)
       
        for col = 1:1:colCount
        {
            set ..%data(rows,"Members")=idList.%Get(rows-1)
        }
    }
    quit$$$OK

この時点で、KPI をコンパイルし、KPI データソースを使ってダッシュボードにウィジェットを作成します。

 

以上です！ InterSystems IRIS の ObjectScript アプリケーションで Pandas の統合と使用のプロセスを確認できました。 このプロセスでは、データのフェッチと整形から絞り込みと表示までを 1 つの合理化された関数で行いました。 この実演では、データ分析における Pandas の効率性と力がハイライトされています。 では次に、IRIS 環境内で Pandas を実装する際の実用的な推奨事項を詳しく見て、変換による影響に関するインサイトで締めくくりましょう。
IRIS における実用的な Pandas アプリケーションの推奨事項

• プロトタイピングから始める:

サンプルのデータセットとユーティリティを使用して Pandas での作業を始めましょう。 この方法によって、制御された使い慣れた環境で Pandas の基本と意味合いを理解できます。 プロトタイピングでは、ライブデータに関連するリスクを伴うことなく、様々な Pandas 関数とメソッドを実験できます。

• 段階的な実装:

既存のデータプロセスに Pandas を徐々に導入しましょう。 全面的に変更するのではなく、Pandas によってデータ処理と分析が強化または単純化されるエリアを特定します。 データクリーニング集計などの単純なタスクであることも、Pandas の機能を完全に活用できるより複雑な分析であることもあります。

•  Pandas の使用を最適化する:

大きなデータセットで作業する前に、Pandas コードを最適化しておくことが重要です。 コードの効率によって、処理時間やリソース消費量が大幅に削減されるため、大規模なデータ分析では特に重要です。 ベクトル化操作、適切なデータ型の使用、データ操作でのループの回避といった手法によって、パフォーマンスは大幅に強化されます。

まとめ

InterSystems IRIS プラットフォームの ObjectScript アプリケーションへの Pandas の統合は、データ分析の分野における著しい進歩です。 Pandas によってデータ処理、分析、および可視化に使用できる多数の強力なツールを使用できるようになり、IRIS ユーザーはこれを使用できるようになりました。 この統合は KPI の開発と分析を高速化して単純化するだけでなく、IRIS エコシステム内でのより洗練された高度なデータ分析機能への道も切り開いています。
 
Pandas を使用することで、アナリストと開発者は、その広範な機能を活用してデータからより深い洞察を得ることで、データ分析の新たな地平を探ることができます。 大規模なデータセットを効率的に処理して分析する能力に、魅力的な可視化の作成しやすさを合わせ、ユーザーはより多くの情報に基づいた意思決定を行い、これまで検出が困難であった傾向やパターンを明らかにできるようになります。
 
要約すると、InterSystems IRIS 環境への Pandas の統合は変革的なステップであり、プラットフォームの機能を強化し、増え続ける最新のデータ分析の課題と複雑さに取り組むための拡張されたツールキットをユーザーに提供することができます。

開発者の皆さん、こんにちは！

次のInterSystems プログラミングコンテストの内容についてご案内します📣

🏆 InterSystems Python コンテスト 🏆

期間：2024年7月15日～2024年8月4日

賞金総額：$14,000

これは InterSystems FAQ サイトの記事です。

PythonスクリプトファイルやPythonで記述されたIRIS内メソッドを呼び出す際、エラーが発生した場合の対応方法をご紹介します。

説明使用するコードや資料PDFは公開しています👉 test1.py、FS.Utilsクラス、コードのコピー元、ビデオで解説している資料PDF

Embedded Python 自習用ビデオをご用意しています（項目別にYouTubeプレイリストをご用意しています）。

各プレイリストについて詳しくはこちらをご参照ください👉【はじめてのInterSystems IRIS】Embedded Python セルフラーニングビデオシリーズ公開！

我々には、Redditユーザーが書いた、おいしいレシピデータセット がありますが, 情報のほとんどは投稿されたタイトルや説明といったフリーテキストです。埋め込みPythonやLangchainフレームワークにあるOpenAIの大規模言語モデルの機能を使い、このデータセットを簡単にロードし、特徴を抽出、分析する方法を紹介しましょう。

データセットのロード

まず最初に、データセットをロードするかデータセットに接続する必要があります。

これを実現するにはさまざまな方法があります。たとえばCSVレコードマッパーを相互運用性プロダクションで使用したり csvgenのようなすばらしい OpenExchange アプリケーションを使用することもできます。

今回、外部テーブルを使用します。これは物理的に別の場所に保存されているデータをIRIS SQLで統合する非常に便利な機能です。

まずは外部サーバ(Foreign Server)を作成します。

CREATE FOREIGN SERVER dataset FOREIGN DATA WRAPPER CSV HOST '/app/data/'

その上でCSVファイルに接続する外部テーブルを作成します。

CREATE FOREIGN TABLE dataset.Recipes (
  CREATEDDATE DATE,
  NUMCOMMENTS INTEGER,
  TITLE VARCHAR,
  USERNAME VARCHAR,
  COMMENT VARCHAR,
  NUMCHAR INTEGER
) SERVER dataset FILE 'Recipes.csv' USING
{
  "from": {
    "file": {
       "skip": 1
    }
  }
}

以上です。すぐに「dataset.Recipes」にSQLクエリを実行できます。

## どんなデータが必要？

データセットは興味深く、直ぐに処理したいと思うのですが、調理のレシピを決めたいのであれば、分析に使える情報がもう少し必要です。 ２つの永続化クラス（テーブル）を使用します。

• yummy.data.Recipe抽出、分析したいレシピのタイトルと説明、他のプロパティが入ったクラス (例: スコア、難易度、材料、調理タイプ、準備時間)
• yummy.data.RecipeHistory レシピのログを取るためのシンプルなクラス

これで 「yummy.data*」 テーブルにデータセットの内容をロードすることができます。

do ##class(yummy.Utils).LoadDataset()

一見良さそうに見えますが、スコア、難易度、材料、準備時間、調理時間フィールドのデータをどのように生成するのかを見つける必要があります。

## レシピの分析 各レシピのタイトルと説明を処理します

• 難易度, 材料, 調理タイプなどの抽出
• 何を作りたいか決められるよう、基準に基づいて独自のスコアを構築

以下を使用します

• yummy.analysis.Analysis

• より多くの分析を構築したい場合に再利用できる一般的な分析構造

• yummy.analysis.SimpleOpenAI - 埋め込み Python + Langchain フレームワーク + OpenAI LLM モデルを使った分析。

LLM(大規模言語モデル)は自然言語を処理するための本当に素晴らしいツールです。

LangChainはPythonで動くようになっているので、Embedded Pythonを使ってInterSystems IRISで直接使うことができます。 LangChain is ready to work in Python, so we can use it directly in InterSystems IRIS using Embedded Python.

完全な SimpleOpenAI クラスは以下のようになります。

/// レシピ向けのシンプルな OpenAI 分析
Class yummy.analysis.SimpleOpenAI Extends Analysis
{

Property CuisineType As %String;

Property PreparationTime As %Integer;

Property Difficulty As %String;

Property Ingredients As %String;

/// 実行
/// ターミナルから実行できます。
/// set a = ##class(yummy.analysis.SimpleOpenAI).%New(##class(yummy.data.Recipe).%OpenId(8))
/// do a.Run()
/// zwrite a
Method Run()
{
    try {
        do ..RunPythonAnalysis()

        set reasons = ""

        // 好きな調理タイプ
        if "spanish,french,portuguese,italian,korean,japanese"[..CuisineType {
            set ..Score = ..Score + 2
            set reasons = reasons_$lb("It seems to be a "_..CuisineType_" recipe!")
        }

        // 丸一日調理に費やしたくない :)
        if (+..PreparationTime < 120) {
            set ..Score = ..Score + 1
            set reasons = reasons_$lb("You don't need too much time to prepare it") 
        }
        
        // 好きな材料ボーナス
        set favIngredients = $listbuild("kimchi", "truffle", "squid")
        for i=1:1:$listlength(favIngredients) {
            set favIngred = $listget(favIngredients, i)
            if ..Ingredients[favIngred {
                set ..Score = ..Score + 1
                set reasons = reasons_$lb("Favourite ingredient found: "_favIngred)
            }
        }

        set ..Reason = $listtostring(reasons, ". ")

    } catch ex {
        throw ex
    }
}

/// 分析結果でレシピを更新する
Method UpdateRecipe()
{
    try {
        // 親クラスの処理を先に呼び出す
        do ##super()

        // 個別のOpenAI 解析結果を追加
        set ..Recipe.Ingredients = ..Ingredients
        set ..Recipe.PreparationTime = ..PreparationTime
        set ..Recipe.Difficulty = ..Difficulty
        set ..Recipe.CuisineType = ..CuisineType

    } catch ex {
        throw ex
    }
}

/// 埋め込み Python + Langchain で分析を実行
/// do ##class(yummy.analysis.SimpleOpenAI).%New(##class(yummy.data.Recipe).%OpenId(8)).RunPythonAnalysis(1)
Method RunPythonAnalysis(debug As %Boolean = 0) [ Language = python ]
{
    # load OpenAI APIKEY from env
    import os
    from dotenv import load_dotenv, find_dotenv
    _ = load_dotenv('/app/.env')

    # account for deprecation of LLM model
    import datetime
    current_date = datetime.datetime.now().date()
    # date after which the model should be set to "gpt-3.5-turbo"
    target_date = datetime.date(2024, 6, 12)
    # set the model depending on the current date
    if current_date > target_date:
        llm_model = "gpt-3.5-turbo"
    else:
        llm_model = "gpt-3.5-turbo-0301"

    from langchain.chat_models import ChatOpenAI
    from langchain.prompts import ChatPromptTemplate
    from langchain.chains import LLMChain

    from langchain.output_parsers import ResponseSchema
    from langchain.output_parsers import StructuredOutputParser

    # init llm model
    llm = ChatOpenAI(temperature=0.0, model=llm_model)

    # prepare the responses we need
    cuisine_type_schema = ResponseSchema(
        name="cuisine_type",
        description="What is the cuisine type for the recipe? \
                     Answer in 1 word max in lowercase"
    )
    preparation_time_schema = ResponseSchema(
        name="preparation_time",
        description="How much time in minutes do I need to prepare the recipe?\
                     Anwer with an integer number, or null if unknown",
        type="integer",
    )
    difficulty_schema = ResponseSchema(
        name="difficulty",
        description="How difficult is this recipe?\
                     Answer with one of these values: easy, normal, hard, very-hard"
    )
    ingredients_schema = ResponseSchema(
        name="ingredients",
        description="Give me a comma separated list of ingredients in lowercase or empty if unknown"
    )
    response_schemas = [cuisine_type_schema, preparation_time_schema, difficulty_schema, ingredients_schema]

    # get format instructions from responses
    output_parser = StructuredOutputParser.from_response_schemas(response_schemas)
    format_instructions = output_parser.get_format_instructions()
    
    analysis_template = """\
    Interprete and evaluate a recipe which title is: {title}
    and the description is: {description}
    
    {format_instructions}
    """
    prompt = ChatPromptTemplate.from_template(template=analysis_template)

    messages = prompt.format_messages(title=self.Recipe.Title, description=self.Recipe.Description, format_instructions=format_instructions)
    response = llm(messages)

    if debug:
        print("======ACTUAL PROMPT")
        print(messages[0].content)
        print("======RESPONSE")
        print(response.content)

    # populate analysis with results
    output_dict = output_parser.parse(response.content)
    self.CuisineType = output_dict['cuisine_type']
    self.Difficulty = output_dict['difficulty']
    self.Ingredients = output_dict['ingredients']
    if type(output_dict['preparation_time']) == int:
        self.PreparationTime = output_dict['preparation_time']

    return 1
}

}

「RunPythonAnalysis」メソッドがOpenAIが詰め込むところです :)　 ターミナルから直接実行してレシピを受け取れます。

do ##class(yummy.analysis.SimpleOpenAI).%New(##class(yummy.data.Recipe).%OpenId(12)).RunPythonAnalysis(1)

以下のような出力を受け取れます。

USER>do ##class(yummy.analysis.SimpleOpenAI).%New(##class(yummy.data.Recipe).%OpenId(12)).RunPythonAnalysis(1)
======実際の課題
                    レシピタイトルを解釈、評価: 巻きずし - アラスカロール
                    説明: 寿司がたべたいのに巻きすがない？ 代わりに簡単なバージョンを試してみてください。超簡単なのに、同じようにおいしい！
[Video Recipe](https://www.youtube.com/watch?v=1LJPS1lOHSM)
# 材料
提供量:  \~サンドイッチ５枚分
* 米１カップ
* 水 3/4 カップ + 大さじ 2 1/2
* 昆布 小口切り １枚
* 米酢 大さじ２
* さとう 大さじ１
* 塩 小さじ1
* アボカド ２個
* カニカマ ６個
* 和風マヨ 大さじ2
* サーモン 1/2 ポンド  
# レシピ     
* 酢飯1合をボウルに入れ、2回以上、または水が透明になるまで米を洗う。炊飯器に米を移し、昆布の小口切り1枚と水3/4カップ＋大さじ2と1/2杯を加える。炊飯器の指示に従って炊く。
* 米酢大さじ2、砂糖大さじ1、塩小さじ1を中くらいのボウルに入れる。全体がよく混ざるまで混ぜる。
* 炊き上がったら昆布を取り除き、すぐに酢を入れた中ボウルに米をすべてすくい入れ、飯ベラを使ってよく混ぜる。米をつぶさないように、切るように混ぜること。炊きあがったら、キッチンタオルをかけて室温まで冷ます。
* アボカド1個の上部を切り、アボカドの中央に切り込みを入れ、ナイフに沿って回転させる。次にアボカドを半分ずつ取り、ひねる。その後、ピットのある側を取り、慎重にピットに切り込みを入れ、ひねって取り除く。その後、手で皮をむく。この手順をもう片方のアボカドでも繰り返す。作業スペースを確保するため、作業台を片付けるのを忘れずに。次に、アボカドを下向きに置き、薄くスライスする。スライスしたら、ゆっくりと広げていく。それが終わったら、脇に置いておく。
* カニカマから包みをはずす。カニカマを縦にむいていく。すべてのカニカマを剥いたら、横に回転させながら細かく刻み、和風マヨ（大さじ2）とともにボウルに入れ、全体がよく混ざるまで混ぜる。
* 鋭利なナイフを斜めに入れ、木目に逆らって薄くスライスする。切り口の厚さは好みによる。ただ、すべてのピースが同じような厚さになるようにする。
* 海苔巻きラップを手に取る。キッチンバサミを使い、海苔巻きラップの半分の位置から切り始め、ラップの中心を少し過ぎるまで切る。ラップを垂直に回転させ、作り始める。すし飯を握るために、手に水をつけておく。酢飯を手に取り、海苔巻きの左上の四辺に広げる。次に、右上にサーモンを2切れ並べる。右下にアボカドを2切れのせる。最後に左下にカニサラダを小さじ2杯ほどのせる。次に、右上の四つ角を右下の四つ角に折り込み、さらに左下の四つ角に折り込む。最後に、左上の四つ角をサンドイッチの残りの部分に折り込む。その後、ラップを上に置き、半分に切って、生姜とわさびを2、3枚添えれば出来上がり。
                    
                    出力は、先頭と末尾の"``json "と"``"を含む、以下のスキーマでフォーマットされたマークダウンのコードスニペットでなければなりません：
json
{
        "cuisine_type": string  // レシピの調理タイプは？                                  小文字の1単語で回答
        "preparation_time": integer  // レシピの準備に必要な時間(分)は？　整数で回答（不明な場合はnull）
        "difficulty": string  // レシピの難易度は？                               「容易」「標準」「難しい」「とても難しい」のうちから１つを回答
        "ingredients": string  // 小文字のカンマ区切りの材料リスト、不明な場合は空
}

                    
======応答
json
{
        "cuisine_type": "japanese",
        "preparation_time": 30,
        "difficulty": "easy",
        "ingredients": "sushi rice, water, konbu, rice vinegar, sugar, salt, avocado, imitation crab sticks, japanese mayo, salmon"
}

良さそうです。OpenAIのプロンプトは有用な情報を返してくれるようです。ターミナルから分析クラス全体を実行してみましょう：

set a = ##class(yummy.analysis.SimpleOpenAI).%New(##class(yummy.data.Recipe).%OpenId(12))
do a.Run()
zwrite a

USER>zwrite a
a=37@yummy.analysis.SimpleOpenAI  ; <OREF>
+----------------- general information ---------------
|      oref value: 37
|      class name: yummy.analysis.SimpleOpenAI
| reference count: 2
+----------------- attribute values ------------------
|        CuisineType = "japanese"
|         Difficulty = "easy"
|        Ingredients = "sushi rice, water, konbu, rice vinegar, sugar, salt, avocado, imitation crab sticks, japanese mayo, salmon"
|    PreparationTime = 30
|             Reason = "It seems to be a japanese recipe!. You don't need too much time to prepare it"
|              Score = 3
+----------------- swizzled references ---------------
|           i%Recipe = ""
|           r%Recipe = "30@yummy.data.Recipe"
+-----------------------------------------------------

## 全レシピを解析する！

当然、読み込んだすべてのレシピで分析を実行したいでしょう。 この方法でレシピ ID の範囲を分析することができます

USER>do ##class(yummy.Utils).AnalyzeRange(1,10)
> Recipe 1 (1.755185s)
> Recipe 2 (2.559526s)
> Recipe 3 (1.556895s)
> Recipe 4 (1.720246s)
> Recipe 5 (1.689123s)
> Recipe 6 (2.404745s)
> Recipe 7 (1.538208s)
> Recipe 8 (1.33001s)
> Recipe 9 (1.49972s)
> Recipe 10 (1.425612s)

その後、レシピテーブルを再度表示させ、結果をチェックします。

select * from yummy_data.Recipe

どんぐりカボチャのピザか、豚肉入り韓国風豆腐キムチを試してみます:） いずれにせよ、家で再確認する必要がありますね :）

最後に

サンプルソースは全て https://github.com/isc-afuentes/recipe-inspector にあります。

この簡単な例で、InterSystems IRIS で LLM テクニックを使用して機能を追加したり、データの一部を分析する方法を学びました。

これを起点に以下のことが考えられます

• InterSystems BIを使い、キューブやダッシュボードでデータの検索やナビゲートをおこなう。
• Webアプリを作成し、UIを提供する（例：Angular）RESTForms2のようなパッケージを活用することで、永続クラスへのREST APIを自動的に生成することができます。 *レシピが好きか嫌いかを保存し、新しいレシピが好きかどうかを判断するのはいかがでしょうか。IntegratedMLアプローチ、あるいはLLMアプローチでいくつかの例データを提供し、RAG(Retrieval Augmented Generation)ユースケースを構築してみるのも良いでしょう。

他にどんなことが試せそうでしょうか？ご意見をお聞かせください！

みなさんこんにちは！ 今回は、IRIS 2024.1で実験的機能として実装されたVector Search (ベクトル検索)について紹介します。ベクトル検索は、先日リリースされたIRIS 2024.1の早期アクセスプログラム(EAP)で使用できます。IRIS 2024.1については、こちらの記事をご覧ください。

ベクトル検索でどんなことができるの？

ChatGPTをきっかけに、大規模言語モデル(LLM)や生成AIに興味を持たれている方が増えていると思います。開発者の方々の中には、中はどうなっているのか気になっている方も多いのではないでしょうか。実は、LLMや生成AIの仕組みを理解したいと思えば、ベクトルの理解は不可欠な要素となります。

ベクトルとは？

ベクトルは、高校の数学で習う「あの」ベクトルのことです。が、今回は、複数の数値をまとめて扱うデータ型であるという理解で十分です。例えば、

( 1.2, -4.5 )

という感じです。この例は、1.2と-4.5という2つの数値をまとめており、数値の個数（ここでは2）のことを次元数と言います。我々の生きている場所を3次元空間と呼ぶことがありますが、これは、3つの数値で場所が特定できることを表しています（例えば、緯度、経度、標高の3つで地球上の位置を完全に特定できます）。

ベクトルをどのように使うのか？

大規模言語モデル（OpenAI の GPT-4 など）の発明と一般化によって、最近までは手動での処理が非現実的または不可能ですらあった大量の非構造化データを使用できる革新的なソリューションの波が押し寄せています。 データ検索（検索拡張生成に関する優れた紹介については、Don Woodlock の ML301 コースをご覧ください）、センチメント分析、完全自律型の AI エージェントなど、様々なアプリケーションが存在します。

この記事では、IRIS テーブルに挿入するレコードに自動的にキーワードを割り当てる単純なデータタグ付けアプリケーションの構築を通じて、IRIS の Embedded Python 機能を使って、Python OpenAI ライブラリに直接インターフェース接続する方法をご紹介します。 これらのキーワードをデータの検索と分類だけでなく、データ分析の目的に使用できるる単純なデータタグ付けアプリケーションを構築します。ユースケースの例として、製品の顧客レビューを使用します。

要件

• IRIS の実行インスタンス
• OpenAPI API キー（こちらで作成できます）
• 構成済みの開発環境（この記事では VS Code を使用します）

Review クラス

顧客レビューのデータモデルを定義する ObjectScript クラスの作成から始めましょう。 簡潔さを維持するために、顧客の名前、製品名、レビュー本文、および生成するキーワードの 4 つの %String フィールドのみを定義します。 クラスはオブジェクトをディスクに保存できるように、%Persistent を拡張します。

Class DataTagging.Review Extends%Persistent
{
Property Name As%String(MAXLEN = 50) [ Required ];Property Product As%String(MAXLEN = 50) [ Required ];Property ReviewBody As%String(MAXLEN = 300) [ Required ];Property Keywords As%String(MAXLEN = 300) [ SqlComputed, SqlComputeOnChange = ReviewBody ];
}

ReviewBody への挿入または更新時に、Keywords プロパティが自動的に計算されるようにしたいため、これを SqlComputed とします。計算される値についての詳細は、こちらをご覧ください。

KeywordsComputation メソッド

次に、レビュー本文に基づいてキーワードを計算するために使用するメソッドを定義します。 公式の openai Python パッケージを直接操作するために、Embedded Python を使用できます。 ただし、先にそれをインストールしておく必要があります。 以下のシェルコマンドを実行しましょう。

<your-IRIS-installation-path>/bin/irispip install --target <your-IRIS-installation-path>/Mgr/python openai

OpenAI のチャット補完 API を使用して、キーワードを生成できるようになりました。

ClassMethod KeywordsComputation(cols As %Library.PropertyHelper) As %String [ Language = python ]
{
    '''
    This method is used to compute the value of the Keywords property
    by calling the OpenAI API to generate a list of keywords based on the review body.
    '''from openai import OpenAI
client = OpenAI(
    <span class="hljs-comment"># Defaults to os.environ.get("OPENAI_API_KEY")</span>
    api_key=<span class="hljs-string">"&lt;your-api-key&gt;"</span>,
)

<span class="hljs-comment"># Set the prompt; use few-shot learning to give examples of the desired output</span>
user_prompt = <span class="hljs-string">"Generate a list of keywords that summarize the content of a customer review of a product. "</span> \
            + <span class="hljs-string">"Output a JSON array of strings.\n\n"</span> \
            + <span class="hljs-string">"Excellent watch. I got the blue version and love the color. The battery life could've been better though.\n\nKeywords:\n"</span> \
            + <span class="hljs-string">"[\"Color\", \"Battery\"]\n\n"</span> \
            + <span class="hljs-string">"Ordered the shoes. The delivery was quick and the quality of the material is terrific!.\n\nKeywords:\n"</span> \
            + <span class="hljs-string">"[\"Delivery\", \"Quality\", \"Material\"]\n\n"</span> \
            + cols.getfield(<span class="hljs-string">"ReviewBody"</span>) + <span class="hljs-string">"\n\nKeywords:"</span>
<span class="hljs-comment"># Call the OpenAI API to generate the keywords</span>
chat_completion = client.chat.completions.create(
    model=<span class="hljs-string">"gpt-4"</span>,  <span class="hljs-comment"># Change this to use a different model</span>
    messages=[
        {
            <span class="hljs-string">"role"</span>: <span class="hljs-string">"user"</span>,
            <span class="hljs-string">"content"</span>: user_prompt
        }
    ],
    temperature=<span class="hljs-number">0.5</span>,  <span class="hljs-comment"># Controls how "creative" the model is</span>
    max_tokens=<span class="hljs-number">1024</span>,  <span class="hljs-comment"># Controls the maximum number of tokens to generate</span>
)

<span class="hljs-comment"># Return the array of keywords as a JSON string</span>
<span class="hljs-keyword">return</span> chat_completion.choices[<span class="hljs-number">0</span>].message.content
}

プロンプト内では、最初に「generate a list of keywords that summarize the content of a customer review of a product」で、製品の顧客レビューのコンテンツを要約するキーワードのリストを GPT-4 でどのように生成するかについての一般的な命令を指定してから、希望する出力と 2 つのサンプル入力を指定していることに注意してください。 次に cols.getfield("ReviewBody") を挿入し、「Keywords:」の語でプロンプトを終了することで、私が提示した例と同じ形式でキーワードを提供して、文を完成させるように促しています。 これは、Few-Shot プロンプティング手法の単純な例です。

この記事を簡潔にするため、キーワードを JSON 文字列で格納するようにしていますが、本番では、DynamicArray に格納するのがお勧めです。ただ、これについては各開発者にお任せします。

キーワードの生成

それでは、管理ポータルで以下の SQL クエリを使用してテーブルに行を挿入し、データタグ付けアプリケーションをテストしてみましょう。

INSERTINTO DataTagging.Review (Name, Product, ReviewBody)
VALUES ('Ivan', 'BMW 330i', 'Solid car overall. Had some engine problems but got everything fixed under the warranty.')

以下のとおり、4 つのキーワードが自動的に生成されました。 上出来です！

まとめ

まとめると、Python コードを埋め込む InterSystems IRIS の機能によって、非構造化データを処理する際に幅広い可能性を得られます。 OpenAI の力を活用して自動データタグ付けを行うのは、この強力な機能によって達成できることの一例にすぎません。 これにより、ヒューマンエラーを縮小し、全体的な効率をさらに高めることができます。

これは、InterSystems FAQサイトの記事です。

Pythonで、IRISサーバ外部から、IRISの処理を呼び出したりIRISのデータを扱いたい場合には、Native API for Pythonを使用します。
モジュールのインポートは、

import irisnative

で、行います。
詳細は、下記ドキュメント及び、各関連トピックをご参照ください。
[ドキュメント] InterSystems Native SDK for Python

一方、IRISサーバ内からPythonでIRISにアクセスする場合は、組み込みPython(Embedded Python）を使用することができます。
モジュールのインポートは、

import iris 

で行います。

詳細は、下記ドキュメント、及び、各関連トピックをご参照ください。
[ドキュメント] 組み込みPython