JinbaとOpenAIで文書から構造化データを抽出

概要

  • OPENAI_INVOKEはJinbaのワークフローからOpenAI APIを呼び出し、後続ステップ向けにJSONを返します。
  • OpenAIキーをJinbaの認証情報システムに保存し、ステップにconfig(version、prompt)とinput.textを設定します。
  • 明示的なJSON指示、スキーマのキー、少数の例を使い、モデルが一貫した構造を返すようにします。
  • SnowflakeやGoogle Sheetsへ送る前に、Jinba Modules Checker V2で出力を検証します。
  • Jinba Flowでは、この抽出ワークフローをオンプレミスで構築し、数日で後続システムへつなげられます。

非構造化テキストからの構造化データ抽出は、多くのデータパイプラインで過小評価されるステップです。テンプレート方式は文書のレイアウトが変わると失敗します。OCRは構造ではなくテキストを生成します。抽出自体が処理の障害になります。

JinbaのOPENAI_INVOKEツールは、これに直接対応します。ワークフロー内からOpenAI APIを呼び出し、JSONオブジェクトを返し、Snowflakeへの挿入やGoogle Sheetsへの書き込みなどの後続ステップへ渡します。このガイドは、認証情報、YAMLの形式、プロンプト設計、後続への接続、その後の決定論的な検証など、連携に必要な設定を扱います。

構造化データ抽出で行うこと

構造化抽出は、自由形式のテキストを定義済みのJSONスキーマへ変換します。抽出したオブジェクトは、分析、報告、データウェアハウスへの取り込みのためにプログラムからアクセスできます。

この設計は、さまざまな業界に適用できます。

  • 金融サービス:融資審査のため、銀行明細から融資申請者の詳細を取得
  • 医療:手作業の転記ミスを減らすため、診療記録から患者のフィールドを抽出
  • Eコマース:製品開発のため、製品レビューを感情スコアと機能への言及に解析

どの場合も、原文はレイアウトや表現が異なります。モデルを使う方式は、文書の種類ごとに別のテンプレートを必要とせず、違いを扱えます。この種の問題でルールベースの解析器に対するOpenAIワークフロー自動化の中核的な利点です。

ステップ1:OpenAI APIキーを取得・保存

APIキーは、OPENAI_INVOKEがOpenAIへ送るすべてのリクエストを認証します。生成手順:

  1. アカウントを作成する場所はplatform.openai.com
  2. です。その後メールアドレスを確認します。
  3. ログインしてプロフィールアイコンをクリックし、View API keys
  4. を選び、Create new secret key
  5. をクリックして、直ちにコピー・保存します。この画面を離れると再表示されません。

生成後は、ワークフローのYAMLやソースリポジトリではなく、Jinbaの認証情報システムへ保存します。Jinbaは実行時に保存した認証情報を解決し、キーをバージョン管理や実行ログから除外します。

支出を管理するため、本番に接続する前にOpenAIアカウントで使用量の上限を設定します。OpenAIの料金はモデルごとに異なり、gpt-4はgpt-3.5-turboよりトークン単価が大幅に高くなります。抽出タスクの複雑さにモデルを合わせます。

ステップ2:ワークフローでOPENAI_INVOKEを設定

OPENAI_INVOKEツールは、最上位のブロックとしてconfigとinputを受け取ります。どちらも複数形ではなく単数形です。

configにモデル設定を入れます。

  • version:OpenAIモデルの識別子。たとえばgpt-3.5-turboやgpt-4
  • prompt:抽出スキーマの定義を含む、モデルへの指示

inputに処理対象のデータを入れます。

  • text:抽出元となる非構造化コンテンツ

完全なステップの設定例:

- tool: OPENAI_INVOKE
config:
version: "gpt-3.5-turbo"
prompt: "Extract the full name, email address, and company from the following text.
Return the result as a JSON object with the keys 'name', 'email', and 'company'."
input:
text: "Contact person: Jane Doe from ExampleCorp. Reach her at jane.doe@examplecorp.com for inquiries."

versionフィールドが、リクエストを処理するモデルを決めます。短く、構造が一貫した文書の抽出には、gpt-3.5-turboが良好に動作し、トークン費用を抑えます。長く、複雑または曖昧なレイアウトの文書には、gpt-4がより信頼できる出力を生成します。

ステップ3:一貫したJSONを生成するプロンプトを記述

プロンプトは、ワークフローとモデルの間の契約です。曖昧な指示は出力構造を不一致にし、特定のキー名に依存する後続ステップを壊します。

次の3つの実践により、OPENAI_INVOKEから信頼できるJSONを得られます。

JSONを明示的に指示する。出力がJSONオブジェクトでなければならないと記載し、形式を暗黙にしません。

プロンプトにスキーマを定義する。後続で参照する全キーの名前を指定します。重要な場合は期待する型も含めます。たとえばmonthly_rentを文字列でなく数値にすると指定します。

少数の例を使う。プロンプトに1つの具体例を入れると、特に表現が不規則な文書で、形式の逸脱を大幅に減らします。モデルは例を目標の構造として扱います。

この3つを使う賃貸契約の抽出プロンプト:

You are an assistant that extracts key information from lease agreements into JSON.

Example:
Text: 'This lease is between Landlord John Smith and Tenant Sarah Johnson for the
property at 123 Main St, starting June 1, 2024, for $2000/month.'
JSON: {"landlord_name": "John Smith", "tenant_name": "Sarah Johnson",
"property_address": "123 Main St", "start_date": "2024-06-01", "monthly_rent": 2000}

Now extract from the following:
{lease_document_text}

対象文書を見る前に、この構造でモデルを正確な出力形式に合わせます。

ステップ4:JSONの結果を後続へ渡す

Jinbaは、{{steps.<step_id>.result}}という形式の結果参照でステップの出力を解決します。OPENAI_INVOKEの完了後、解析済みのJSONオブジェクトは、すべての後続ステップで利用できます。

抽出フィールドをSnowflakeに挿入する例:

- tool: SNOWFLAKE_QUERY
config:
credential: snowflake_prod
input:
query: >
INSERT INTO contacts (name, email, company)
VALUES (
'{{steps.OPENAI_INVOKE.result.name}}',
'{{steps.OPENAI_INVOKE.result.email}}',
'{{steps.OPENAI_INVOKE.result.company}}'
);

Google Sheetsへの書き込みにも同じ参照形式を使います。抽出JSONの各フィールドを、{{steps.OPENAI_INVOKE.result.<key>}}で対応する列へ割り当てます。

後続は、定期確認や外部の状態確認ではなく、Jinbaの結果参照システムで抽出出力を受け取ります。以前の結果を参照するステップは、その結果が利用可能になってから実行するため、暗黙の依存関係管理になります。

抽出後の検証:Modules Checker V2

OPENAI_INVOKEは確率的に動作します。同じ入力で続けて実行しても、通常はプロンプトのスキーマに従うものの、毎回ではありません。フィールドが欠け、キー名が変わり、数値が文字列で返されることがあります。開発時にプロンプトを試して、検証層なしに導入することが、本番の抽出ワークフローで最も一般的な失敗点です。

Jinba Modules Checker V2は、OPENAI_INVOKEを補完する決定論的な機能です。結果が後続システムに達する前に、抽出JSONを定義済みルールで検証します。必須フィールド、データ型、値の制約を、確率に基づく標本検査ではなく、厳格なルールとして強制します。

信頼できる抽出の2段階設計:

  1. OPENAI_INVOKEが、レイアウトに依存しない柔軟な抽出を行い、JSONオブジェクトを返す
  2. Jinba Modules Checker V2が検証し、ルール違反があれば、不正な記録がSnowflakeやSheetsに届く前に停止する

この分離は両ツールの役割を保ちます。LLMは原文の違いと曖昧さを扱い、チェッカーは後続システムが求めるスキーマの契約を強制します。どちらも他方の代わりではありません。

ガバナンス:監査ログ、キーの保護、非公開モデル

Jinbaの企業ワークフロー処理制御は、各ステップの入力、出力、判断を含め、実行ごとに完全な監査ログを記録します。財務記録、契約、個人を識別できる情報を処理する抽出ワークフローでは、これが準拠審査の証拠の連鎖です。

APIキーの保護はステップ1の認証情報ストアの設定に基づきます。Jinbaの認証情報システムのキーは実行時に解決され、YAML、ログ、リポジトリに書き込まれません。更新もストア内で行い、定義は変更しません。

GDPRなどのプライバシー規制が適用されるデータでは、機密テキストを処理するチームは非公開モデルや自己ホスト型モデルが適切か評価します。第三者APIへPIIを送ると、規制当局や顧客契約が許容するデータ処理条件から外れる場合があります。Jinbaは認証情報に基づく振り分けに対応するため、versionフィールドを公開OpenAI APIではなく非公開エンドポイントへ向け、残りの設定を変えずに使えます。

次に構築するもの

Jinbaで動く抽出ワークフローには4つが必要です。

  • OpenAI APIキー。保存先はJinbaの認証情報システム
  • スキーマを定義するプロンプトを持つOPENAI_INVOKEステップと、タスクの複雑さに合わせたversionの設定
  • 出力の契約を強制する、Jinba Modules Checker V2の検証ステップ
  • 後続ステップで参照するのは、{{steps.OPENAI_INVOKE.result.<key>}}です。検証済みデータをSnowflake、Google Sheets、その他の対象へ送ります。

確率的な抽出と決定論的な検証の組み合わせが、このアーキテクチャを試作品水準ではなく、本番で安全に使えるものにします。1つの文書の種類から始め、実際の入力サンプルでスキーマ契約が維持されるか確認してから拡張します。

構築前に、Jinbaツールのドキュメントで利用可能なツール識別子と設定の全一覧を確認します。

よくある質問

JinbaのOPENAI_INVOKEツールは何に使いますか?

OPENAI_INVOKEは、OpenAI APIを呼び出し、非構造化テキストから構造化データを抽出してJSONオブジェクトを返すJinbaのツールです。文書、メール、フォームからフィールドを取得し、SnowflakeやGoogle Sheetsなどの後続システムへ渡すタスク向けです。

JinbaでOPENAI_INVOKEをどう設定しますか?

最上位のブロックは、configとinputです。config内で、versionをOpenAIモデル(例:gpt-3.5-turboまたはgpt-4)に、promptを抽出指示に設定します。input内のtextフィールドに非構造化コンテンツを指定します。完全なステップ例:

- tool: OPENAI_INVOKE
config:
version: "gpt-3.5-turbo"
prompt: "Extract the full name, email address, and company from the following text. Return the result as a JSON object with the keys 'name', 'email', and 'company'."
input:
text: "Contact person: Jane Doe from ExampleCorp. Reach her at jane.doe@examplecorp.com for inquiries."

Jinba用のOpenAI APIキーをどう取得しますか?

platform.openai.comでアカウントを作り、メールを確認し、View API keysへ進み、Create new secret keyをクリックします。再表示されないので直ちにコピー・保存します。その後Jinbaの認証情報システムに保存し、YAMLやソースコードには含めません。Jinbaが実行時にキーを解決して保護します。

一貫したJSONを返すプロンプトはどう書きますか?

JSON出力を明示し、キー名と型を含む正確なスキーマを定義し、希望する形式を示す少数の例を含める、3つの実践を使います。たとえば本番入力の前に、サンプル文と対応するJSONを示し、期待する形式に合わせます。

OPENAI_INVOKEの出力をSnowflakeやGoogle Sheetsへどう渡しますか?

結果参照の形式は{{steps.<step_id>.result.<key>}}です。抽出完了後、JSONの各フィールドにアクセスできます。Snowflakeでは、SNOWFLAKE_QUERYステップのSQLへ参照を埋め込みます。Google Sheetsでは、同じ形式で各フィールドを列へ割り当てます。Jinbaが依存関係を自動管理し、後続は結果を待ちます。

OPENAI_INVOKEが返すJSONをどう検証しますか?

必須フィールド、型、値の制約でJSONを検証する決定論的なツール、Jinba Modules Checker V2を使います。ワークフローのOPENAI_INVOKE直後に置きます。失敗時は不正なデータが後続へ達する前に停止します。確率的な抽出の後に決定論的な検証を行う2段階の設計は、本番の信頼性に不可欠です。

OPENAI_INVOKEで非公開モデルや自己ホスト型モデルを使えますか?

はい。認証情報に基づく振り分けに対応し、versionを公開APIではなく非公開エンドポイントへ向けられます。GDPRなどの下での機密データ処理を支えます。変わるのはモデルのエンドポイントだけで、残りの設定は同じです。

OpenAIでOPENAI_INVOKEを使う費用はどれくらいですか?

費用はモデルとトークン使用量によります。gpt-3.5-turboはgpt-4より単価が安く、短く構造が一貫した文書には、gpt-3.5-turboで十分です。複雑で長い文書には、gpt-4が必要ですが費用は高くなります。本番接続前にOpenAIアカウントで上限を設定し、料金ページで支出を監視します。

人馬一体のワークフロー構築を体験せよ

エンタープライズ組織を支えるAI基盤

無料で始める