Skip to main content
カスタム アクティビティ スクリプトからは、HTTP や認証、プロバイダー固有のコードを記述することなく、ABBYY が提供・運用する LLM エンドポイント ABBYY Phoenix Plus を呼び出せます。このアクティビティは Process skill の Step として実行されるため、モデルは現在のトランザクションを読み取ることができ、その結果を後続の Step で利用できます。
ABBYY Phoenix Plus は ABBYY Vantage Cloud で利用でき、契約に基づくエンタイトルメントが必要です。お使いのテナントで有効化するには、ABBYY のアカウント チームにお問い合わせください。概要については、ABBYY Vantage における LLM を参照してください。

開始する前に

  • テナントで Phoenix Plus entitlement が有効になっており、ADMIN → Configuration → ConnectionsABBYY Phoenix Model の接続が表示されていること。
  • カスタム アクティビティを含む Process skill があること。手順については、カスタム アクティビティを参照してください。
  • アクティビティの Available Files タブで、スクリプトに必要なエクスポート形式を選択します。ほとんどのスクリプトでは OcrJson が必要です。ページ画像を送信する場合は JPEG のエクスポートも必要となり、アクティビティの実行前に生成しておく必要があります。

チャットセッションの作成

引数なしで Context.CreateLlmChatSession() を呼び出すと、tenant の ABBYY 管理接続に対してセッションが開かれます。接続名を指定した場合は、代わりに tenant 自身の接続のいずれかに対してセッションが開かれます。
このページの以降の内容では、マネージド接続について説明します。ご自身の接続に対して開いたセッションも動作は同じですが、課金はご利用のプロバイダー経由となり、利用権の対象外となります。 セッションで使用されるモデルは、ABBYY が選定し保守します。セッションはモデルの変更をいっさい受け付けないため、マネージド接続を通じて特定のモデルやバージョンを指定することはできません。

セッションのプロパティ

LastUsageTotalUsage は、PromptTokensCompletionTokensTotalTokens を保持するオブジェクトです。

セッションのリセット

Reset() は会話履歴と保留中の添付ファイルをすべてクリアするため、次のメッセージは新しい状態から開始されます。SystemPromptTemperature などの設定は保持され、累積された使用量もそのまま維持されます。

メッセージにコンテンツをアタッチする

モデルに参照させたいトランザクションデータをアタッチしてから送信します。 アタッチしたコンテンツはすぐに送信されるのではなく、次のユーザーメッセージに合わせてキューに入れられます。 何も送信せずに会話履歴を構築することもできます。これは few-shot プライミングに役立ちます。
AttachFileAttachBinary、および汎用の Attach は存在しません。上記のメソッドを使用してください。

ページ順序でページ画像をアタッチする

JPEG のエクスポートは Properties["PageIndex"] の順に並んでいるため、出現順にアタッチすれば、添付ファイルの順序を Model が返すページ番号と一致させたまま維持できます。

メッセージの送信とレスポンスの読み取り

SendJson はオブジェクトを返します。string が返された場合は、Model が解析可能な JSON を生成できなかったことを意味するため、呼び出しを再試行するのではなく prompt をより厳密にする必要があります。

レスポンスがどのように終了したかを確認する

レスポンスを信頼する前に、必ず LastFinishReason を確認してください。値が "length" の場合、レスポンスはトークン上限で打ち切られています。これはエラーではなく、他に知らせる手段もないため、この値を無視する script は、不完全な結果を完全なものとして解析してしまいます。対処方法は、MaxTokens を引き上げるか、field セットを絞り込むことです。

値を書き込む前に構造を検証する

レスポンスが完全な形で返ってきていても、構造が正しいとは限りません。スカラーの field は正しいのに、Skill が定義する繰り返し部分がまったく含まれていない、といったケースです。要求したテーブルや repeating fields がレスポンスに含まれているかを確認し、含まれていない場合は未確認のまま Document に書き込まず、再度問い合わせてください。試行の合間にはセッションをリセットし、その後 SystemPrompt を改めて設定します。

マネージド接続に必要な条件

文書コンテキスト。 文書ページを持たない実行では、マネージド接続は拒否されます。これは、共有のプラットフォーム資格情報が汎用の LLM ゲートウェイとして使われるのを防ぐためです。文書を含むトランザクション上で動作するカスタム アクティビティはこの条件を満たしますが、そのコンテキストの外でセッションを開くスクリプトは満たしません。 課金計測。 マネージド接続経由の呼び出しは、お客様の ABBYY 利用権に対して計測されます。お客様ご自身で構成した接続経由の呼び出しは、代わりにお客様ご自身のプロバイダーから課金されます。大量の再処理ジョブをマネージド接続に向ける前に、その処理量を十分に検討してください。

メッセージの制限

いずれの制限も強制され、どちらか一方でも超過したメッセージはその時点で拒否されます。呼び出しが失敗するのを待つのではなく、送信前にスクリプト内でメッセージのサイズを確認してください。 プロンプトの上限は単一の固定値ではありません。環境ごとに設定され、処理対象のページ数に応じて増加しますが、最大値が定められています。現在のABBYY Vantage Cloudでは、1ページあたり500,000文字が許容され、カウント対象は最大3ページまで、上限は1,500,000文字です。 上限は環境ごとに設定され、変更される可能性があるため、これらの数値は保証された仕様ではなく参考情報として扱ってください。固定の上限を前提とせず、ランタイムでメッセージのサイズを確認し、収まらない場合は処理を縮退させてください。 上限を超えると、次の形式のメッセージが出力されます。

再試行では解決できないエラー

exceeds the maximum allowed sizemaximum number of attachmentscontext lengthtoo large といった文言を含む送信エラーは、再試行しても回復できません。メッセージのサイズが大きすぎるか、含まれる内容が多すぎるため、同じ呼び出しを繰り返しても再び失敗します。対処方法は、JPEG エクスポートの解像度を下げる、送信するページ数を減らす、または画像を省いて OCR の JSON のみで実行する、のいずれかです。

スクリプトで捕捉できないエラー

ほとんどの失敗は、スクリプト内の try/catch で捕捉できます。接続の問題、リクエストの失敗、有効な JSON ではない応答、サイズ制限を超える prompt などです。これらは適切に処理して処理を続行してください。 ただし、リクエスト上限の超過は例外です。 1 回のスクリプトの実行で行える LLM 呼び出しの回数には制限があり、その上限はトランザクションのページ数に応じて変動します。これを超えるとスクリプトは制約エラーで停止し、既存の HTTP request 上限と同じように、try/catch では捕捉できません。 この点は、リトライを行う場合に特に重要です。検証して再度問い合わせるループは実行ごとに 1 回の呼び出しを消費するため、それ自体に上限を持たないループは、いずれ対処できない制限に達してしまいます。リトライ回数には必ず上限を設けてください。

ページ画像の送信

ページ画像も利用できますが、プロンプト予算で決まる実用上の上限があります。 上記の上限に照らした実測例を2つ挙げます。
  • 1584x1000のページ画像1枚は、およそ 311,776 base64文字 とおよそ2,015プロンプトトークンを消費します。1ページのトランザクションであれば500,000文字の上限に収まり、OCR JSONとプロンプトの分の余裕も残ります。
  • 300 dpiでスキャンした2ページのA4帳票は、画像だけでおよそ 1,326,136文字 になります。2ページのトランザクションの上限は1,000,000文字なので、これは拒否されます。画像として送信するには、各ページを300 dpi時のサイズの約4分の1まで縮小する必要があります。
この計算はページ数や環境側の上限の変更によって変わります。だからこそ、収まるはずと決めつけず、送信前にメッセージのサイズを実測しなければなりません。 予算に逆らうのではなく、予算に合わせて設計してください。
  • OCR JSONを主たるペイロードとして送信し、スタンプ、署名、写真など、テキストレイヤーでは表現できないものに限ってページ画像を追加します。
  • 送信前にメッセージを実測します。画像が収まらない場合は画像を外し、それに合わせてプロンプトを組み直して、OCR JSONだけでもDocumentが処理されるようにします。
  • 画像のサイズを決める際はOCR JSONの分の余裕を確保し、大きな画像が座標の取得元となるペイロードを圧迫しないようにします。
  • モデルがレイアウトやスタンプを確認するだけでよく、細部が不要な場合は、エクスポート前に画像解像度を下げます。

位置とバウンディングボックス

モデルに座標を要求しないでください。マネージド接続の背後にあるモデルは、ページ画像上でバウンディングボックスを位置づけることができず、座標のように見えるレスポンスが返っても、それは実測値ではありません。
ページ画像から座標を返すよう求めると、モデルは10単位刻みの格子上の値を返します。すべての数値が10の倍数、高さは一律、異なる2つのfieldが同一のRectangleを共有する、といった具合です。これは実測されたlayoutではなく作り出されたlayoutであり、座標系の設定を変更しても解消されません。 形状は代わりにVantageのOCR layerから取得してください。OCR JSONエクスポートには、layout.pages[].pictures[]barcodes[] を含め、テキストと非テキストの両方のコンテンツについて実測位置が含まれています。そのため、写真、ロゴ、barcodeも単語と同じ信頼性で位置を特定できます。 堅牢なscriptは次のような作りになります。
  • 座標は推定せず、コピーする。 すべてのRectangleはOCR JSON内の位置の値から取得し、OCRのpage sizeと照合して検証し、両者が異なる場合はVantageのページ画像に合わせてスケーリングします。
  • 出自を厳格に確認する。 モデルが返す各Regionは、受け入れる前にOCRの形状と照合して検証します。OCR layerまで遡れないRegionは拒否し、抽出された値そのものは保持します。
  • ページの帰属を必須とする。 複数ページ文書では、ページ番号のないRegionは、既定でページ1とみなさず拒否します。
モデルは、その得意分野である読み取りと分類に使用してください。形状はABBYY OCRに任せましょう。

MaxTokens は意識的に設定する

MaxTokens をプロバイダー の Default のままにしておくと、情報量の多い Document で気づかないうちに切り詰めが発生し、LastFinishReason を見て初めて分かるという事態になりかねません。明示的に設定し、上限を自分で管理・把握できる状態にしてください。 規模の目安として、9 column のテーブルを 3 ページにわたってセル単位で Extract する場合、コンプリーショントークンはおよそ 28,000 になります。

十分な時間を確保する

レイテンシは入力のサイズではなく、生成される 出力 トークン数に応じて増加します。Phoenix Plus が生成するコンプリーショントークンは 1 秒あたり約 100 個のため、28,000 トークンのレスポンスには数分を要します。 Timeout は分単位で設定し、スクリプト実行タイムアウトが上限となります。28,000 個の出力トークンを必要とするドキュメントに 2 分のタイムアウトを設定した場合、約 121 秒の時点で、レスポンスの一部しか生成されないまま失敗します。

送信前にOCRペイロードを削減する

未加工のOCR JSONエクスポートは文字レイヤーが大半を占め、通常はサイズの97~98パーセントに達します。これを削り落とせば、モデルが実際に必要とするテキストと単語の位置だけが残り、promptの予算もごくわずかで済みます。 ある計測事例では、43,437文字のエクスポートが、単語の位置を保持したまま4,842文字まで削減されました。別の事例では、317,296文字のエクスポートが32,712文字になりました。 コストを見積もる際は、OCR JSONはおよそ1トークンあたり2文字として換算します。JSONの記号類はトークン化の効率が悪いため、通常の文章から導き出した比率は当てはまりません。

Known limitations

ページを画像としてアタッチするには、AttachPageImage(page) を使用してください。Page.ImageAttachImage に渡すと、分割済み・未分割のいずれの Document でも Value cannot be null. (Parameter 'fileLink') がスローされます。これは、AttachImage がページの画像プロパティではなく、エクスポート済みのファイルを想定しているためです。Document.Exports から取得した JPEG のエクスポートであれば、AttachImage で正常に動作します。

この script は、絞り込んだ OCR JSON を送信し、形状情報をすべて OCR layer から取得して structured な field 値を要求します。