画像
記憶は画像を保持できます。エンジンが画像そのものをインデックスするため、レコードにキャプション、タイトル、代替テキストがない場合でも、任意の言語のテキストクエリで一致します。
Tablet 2 以降で対応しています。画像を実装していないエンジンは、素の 404 を返すのではなく機能名を挙げて未対応であることを伝えるため、機能がないのか記憶がないのかを区別できます。JPEG、PNG、GIF、WebP に対応します。
保存する
通常の add 呼び出しに image オブジェクトを渡します。content は空でも構いません。その場合、画像だけで検索できます。
mem.add("at the beach", image={"data": b64}) # caption + image
mem.add("", image={"data": b64}) # the image IS the memorydata は必須です。data:image/jpeg;base64, の接頭辞と、base64 や openssl が付ける改行は、どちらも自動で取り除かれます。
| フィールド | 動作 |
|---|---|
| data | 画像の Base64 です。必須。サイズの上限は SDK の定数ではなくサーバー側の設定で、/health が memory.images.max_bytes として報告します。 |
| reference | 元データの自前のコピーが置かれている場所です。文字列として保存されるだけで、こちらから取得することはありません。保持しているのは縮小された画像なので、原本の置き場所はここになります。 |
| taken_at | RFC3339 形式で、通常は EXIF から取得します。event_date が空の場合はこの値で埋められるため、記憶はアップロードされた日時ではなく撮影された日時で並びます。 |
検索する
画像専用の検索はありません。search と recall が、テキストと同じランキングの中で画像も返します。
保存済みの画像を扱う
data, mime = mem.get_image(memory_id=mid)
page = mem.list_images(limit=50) # page["count"] = store total
mem.forget_image(memory_id=mid, preview=True)| 呼び出し | 動作 |
|---|---|
| get_image | こちらが保持している画像を (bytes, content_type) として返します。アップロードされたものそのままとは限りません。長辺が 1,568 px を超えていた画像は縮小して保存されており、JPEG 以外は WebP に再エンコードされるため、PNG を送っても image/webp で返ります。型はアップロード時の名前ではなくバイト列から判定されるので、ファイル名は content_type から付けてください。画像のない記憶では、空の値を返すのではなく例外を送出します。 |
| list_images | 新しい順に 1 ページ分と、ページサイズではなくストア全体の件数である count を返します。ページングはカーソル方式で、next_before と next_skip_ids をそのまま返送します。画像はタイムスタンプが重複しうるため、両方が必要です。 |
| forget_image | 画像を削除し、テキストは残します。キャプションなしで保存された画像は、それ自体が記憶そのものであるため、その場合は記憶も削除されます。 |
forget_image に preview=True を渡すと、何も変更せずに memory_kept を取得できます。iter_images はページングを代行します。
画像の料金
画像もテキストと同じ単位のトークンで計算します。トークン = ピクセル面積 / 556.7。長辺が 1,568 px を超えると 1,568 px 基準で数えるため、2,500 px の画像と 1,568 px の画像は同じ値になります。
| 画像 | 換算基準 | トークン |
|---|---|---|
| 700 × 700 | as sent | 881 |
| 1000 × 1000 | as sent | 1,797 |
| 1568 × 1568 | as sent | 4,417 |
| 1920 × 1080 | 1568 × 882 | 2,485 |
| 2500 × 1875 | 1568 × 1176 | 3,313 |
| 2500 × 2500 | 1568 × 1568 | 4,417 |
画像 1 枚あたりの上限は 4,417 トークンです。呼び出し前にこの上限を残高から確保し、終了後に実測値で請求します。実測値が上限を超えることはありません。
こちらが保持するのは原本ではなく、記憶の解像度まで縮小した画像です。長辺が 1,568 px を超える画像は受け取る時点で 1,568 px に縮小され、索引も保存も返却も、すべてその縮小画像です。縮小には再エンコードが伴うため、可逆形式は WebP で書き出されます。2,500 px の PNG は 1,568 px の
image/webp として返ります。JPEG は JPEG のままで、1,568 px 以下ならバイト列には手を加えません。（再エンコードでファイルが大きくなる場合は、送られたバイト列をそのまま保持します。）短辺・長辺とも 700 px 以上、長辺は 2,500 px 以下という条件は変わらず、外れた場合は 400 で拒否されます。700 px 未満では課金が一律の下限額になるため小さい画像でも保存コストは同じで、2,500 px を超えるものはそもそもデコードしません。フル解像度のファイルが必要な場合は、自前のコピーを保管するか、その URL を reference に入れてください。返る枚数
既定は 1、1 レスポンスあたり最大 5 枚です。5 枚で 20,000 トークン近くになります。
| フィールド | 動作 |
|---|---|
| max_images | 0 から 5 まで。1 つのレスポンスが含められる画像の枚数です。既定は 1 です。0 はテキストのみを返します。範囲外の値は丸められるのではなく拒否されます。 |
画像に英語のキャプションを付けると、英語のクエリは改善し、他の言語のクエリは低下します。14 言語の平均で recall@5 が 11.4 ポイント下がります。利用者が複数の言語で検索する場合は、キャプションなしで画像を保存してください。