コーヒー豆の輸入商社が産地から届く英文の生豆の品質報告書を読み取り、欠点数・水分・スクリーン・カッピングの評価を入荷ロットの台帳に転記して、契約の品質条件と入荷後の検査との差を拾う

処理の起点を決める

受付フォルダ（Amazon S3）に報告書が保存されたことを起点にします。 出荷前の試料は承認を待って船積みが止まっているため、届いた日のうちに照合の結果を出す必要があります。 定時の実行ではなく、届いたその場で動かします。

ファイルは担当者が <ロット番号>_PSS.pdf（出荷前の試料）、<ロット番号>_ARR.pdf（入荷後の検査）の形にして置きます。 末尾で書類の種類を分け、ロット番号で台帳の行と結び付けます。

S3 への保存を AWS Lambda が受け、StartDocumentAnalysis を呼びます。報告書は2〜3ページのことがあるため、非同期にそろえます。 ClientRequestToken にファイルから作った値を入れると、二度置いても同じ JobId が返り、二重に読みません。 完了は Amazon SNS に届き、GetDocumentAnalysis で結果を取ります。結果は既定で7日間しか取れないため、すぐ S3 に保存します。

入力データを集める

質を決めるのは、契約の記録に「評価の用紙」を書くことです。 契約の評価の下限が2004年の用紙の点数で書かれているのに、報告書が CVA の評価なら、数字は並んでも比べられません。 そのときは照合をせず、人に回します。

データの取得方法を決める

読み取りは StartDocumentAnalysis に FeatureTypes として QUERIES、TABLES、FORMS を指定して行います。全文の行と単語は、指定した機能にかかわらず返ります。

欠点は質問ではなく表で取ります。 欠点の種類は十数行あり、表なら列見出しで「名前」「区分」「粒数」「換算した欠点数」の列を分けて取れるからです。 表の CELL には行と列の位置と列見出しの印が付くので、列見出しで列を決めます。

質問は対象のページを指定しないと、既定で1ページ目にしか当たりません。 カッピングの評価は2ページ目以降にあることが多いので、Pages: ["*"] を付けます。

AIへ渡す前に整形する

1. 形式の確認 … JPEG、PNG、PDF、TIFF であること。XFA形式のPDFは扱えません
2. パスワードの確認 … PDFはパスワード保護不可です。解除したものを輸出者に頼みます
3. サイズと寸法の確認 … 非同期の処理で JPEG と PNG は10MB、PDF と TIFF は500MB・3,000ページまで、画像はどの辺も10,000ピクセル以下です
4. 文字の大きさの確認 … 文字の高さが15ピクセル（150 DPIで8ポイント相当）を下回ると検出されません。欠点の表は小さな字なので、縮小しすぎません
5. 言語の確認 … スペイン語・ポルトガル語の報告書は文字は検出できても質問が使えません。全文に英語の見出しがほとんど無ければ、質問を当てずに人に回します
6. 手書きの用紙の確認 … カッピングの用紙の目盛りへの印は、文字ではないため読み取りの対象にしません。合計の欄に書かれた数字だけを読みます

AIに処理させる

させるのは、報告書から決まった項目の値を、物差しと根拠の位置と信頼度を添えて読み取ることだけです。 そろえ方と照合は、読み取りの後にプログラムの規則が行います。

試料の量と用紙の種類を独立して読むのが、この表でいちばん大事なところです。 どちらも報告書の隅に小さく書かれるか、書かれていないことがあります。書かれていなければ basis_unknown・scale_unknown として、数字があっても照合に使いません。

指示内容を固定する

AWS Textract への指示は、英語の質問の一覧です。別名を付けて、受け取る側のプログラムが項目を取り違えないようにします。

QueriesConfig:
  Queries:
    - Text: "What is the lot number or ICO mark?"
      Alias: LOT_NO
      Pages: ["*"]
    - Text: "What is the country and region of origin?"
      Alias: ORIGIN
      Pages: ["*"]
    - Text: "What is the processing method?"
      Alias: PROCESS
      Pages: ["*"]
    - Text: "What is the grade?"
      Alias: GRADE
      Pages: ["*"]
    - Text: "What is the moisture content?"
      Alias: MOISTURE
      Pages: ["*"]
    - Text: "What is the sample weight in grams used for defect count?"
      Alias: SAMPLE_WEIGHT
      Pages: ["*"]
    - Text: "What is the total number of full defects?"
      Alias: TOTAL_DEFECTS
      Pages: ["*"]
    - Text: "What is the total cupping score?"
      Alias: CUP_SCORE
      Pages: ["*"]
    - Text: "Which cupping form or protocol was used?"
      Alias: CUP_FORM
      Pages: ["*"]

受け取った答えと表に対して、プログラムの側で次の決まりを当てます。これが実質的な「指示」です。

【答えと表の扱いの決まり】
1. 答えが空の項目は not_found とする。前回のロットや契約の値で埋めない。
2. 信頼度が決めた値を下回る項目は unreadable とし、値は参考として残す。
3. LOT_NO はファイル名のロット番号と比べ、合わなければ mismatch とし、
   台帳の行に結び付けない。
4. 欠点の表は列見出しで列を決める。見出しが無い表は cannot_parse とし、
   列の位置で決めない。
5. 欠点の名前は項目表で自社の名前と区分にそろえる。表に無い名前は
   unmapped とし、似た名前に寄せない。区分は報告書の区分ではなく
   自社の項目表の区分を使い、報告書の区分は参考として並べる。
6. TOTAL_DEFECTS は表から数え直した値と比べ、違えば
   count_mismatch とする。どちらかに寄せない。
7. SAMPLE_WEIGHT が空なら basis_unknown とし、欠点数を契約の上限と比べない。
8. CUP_FORM と全文の語から、評価の用紙を sca_2004 ／ cva ／ unknown に
   分ける。契約の用紙と違えば scale_mismatch とし、点数を比べない。
9. 水分は % を基準にそろえる。換算の決まりに無い単位は unit_unknown とする。

7番目と8番目が、この構成の要です。 試料の量が違えば同じ欠点数でも意味が違い、用紙が違えば同じ数字でも意味が違います。比べられないものを比べないことを、規則の側で決めておきます。

5番目で報告書の区分を使わないのも、意図してのことです。 同じ欠点を輸出者によって区分1とも区分2とも書くことがあり、基準は自社の側にそろえます。

出力形式を固定する

読み取りと照合の結果を、ロットごとに次の形のJSONにまとめて台帳へ渡します。

{
  "lot_no": "ETH-2026-0412",
  "report_type": "pre_shipment | arrival",
  "attributes": { "origin": "", "process": "", "grade": "" },
  "moisture": { "value": 0, "unit": "%", "status": "ok | unit_unknown | not_found" },
  "defects": {
    "sample_weight_g": 0, "basis": "ok | basis_unknown",
    "rows": [ { "lab_name": "Full Black", "own_name": "full_black",
                "own_category": 1, "lab_category": 1, "count": 0,
                "status": "ok | unmapped" } ],
    "total_report": 0, "total_recount": 0
  },
  "cupping": { "score": 0, "form": "sca_2004 | cva | unknown",
               "status": "ok | scale_unknown | scale_mismatch" },
  "contract_check": [
    { "item": "moisture", "limit": "", "result": "within | out_of_range | cannot_check" }
  ],
  "arrival_diff": [
    { "item": "moisture", "pre_shipment": 0, "arrival": 0, "diff": 0,
      "result": "within | over_tolerance | waiting_arrival" }
  ],
  "verdict": "confirm | review | urgent"
}

1つ目の理由は、数字と物差しを同じ要素に入れておけることです。 defects.basis と cupping.form が数字の隣にあり、台帳を後から読む人にも、何を比べてよいかが分かります。

2つ目は、arrival_diff を後から埋められることです。 出荷前の報告書を読んだ時点では waiting_arrival のまま台帳に置き、入荷後の検査が出たときに同じ行を更新します。

システムへ連携する

輸出者には何も送りません。 承認するか、条件の外れを伝えるかは、品質管理と購買が決めて人が連絡します。 読み違い1つで承認や申し立てが流れる経路を作らないためです。

人が確認する

人が開くのは review と urgent の行だけです。 全件を開く設計にすると、第10章の6.0時間には収まりません。

1. urgent を先に見る … 報告書の画像で、外れた項目の数字と単位を自分の目で読み直します。読み取りの誤りで urgent になっていないかを最初に確かめます
2. 物差しの違いを確かめる … scale_mismatch や basis_unknown は、輸出者に用紙や試料の量を問い合わせるか、自社の検査を待つかを決めます
3. unmapped の欠点の名前を項目表に足す … 同じ調べものを二度しないための作業です
4. 確定する … 読み取りの値と直した値の両方を残します

例外に対処する

記録を残す

• 報告書の元のファイル、AWS Textract の結果の全文（JSON）と JobId
• そろえた後の値とそろえ方の記録、照合の結果とそのときの項目表・判定の決まりの版
• 担当者が直した項目と直す前の値、輸出者に問い合わせた内容と回答
• 輸出者ごとの、出荷前と入荷後の差の傾向

最後の行が、次の買付の材料になります。 産地の評価と自社の評価の差が輸出者ごとに分かれば、どの輸出者の報告書をどれだけ信じてよいかが数字で見えます。