お問い合わせフォームの営業メールを TypeSafe Jev（System One）で判定して StopForumSpam に自動報告する仕組みを作った

TypeSafe に投げているリクエスト#

System One は「state（判定対象）と、型付きの質問」を渡すと、質問ごとに型付きの答えを返す API です。テキストを生成する LLM ではなく、choice なら選択肢ごとの確率、noul なら Yes の確率が返ってきます。JSON のパースやリトライの心配がありません。

今回は choice を1問だけ投げています。実際のコードです。

const KIND_QUESTION = {
  type: "choice",
  instructions: {
    site:
      "合同会社テラレン（神奈川県葉山町）のWebサイトのお問い合わせフォーム。テラレンは不動産管理・別荘管理・不動産運用と、" +
      "無料の自社Webサービス（銀行・支店コード検索API『銀行くん』、郵便番号API『ポストくん』、駅・路線API、法人番号検索『法人くん』、AI TRI+）を運営している。",
    question: "`site` のフォームに届いたこの投稿 `message` はどれにあたるか？",
  },
  criteria: {
    inquiry:
      "テラレン宛ての正当な連絡。物件・別荘の管理や賃貸の相談、不動産オーナーからの相談、自社サービス（API・データ）の使い方・エラー・仕様・利用条件・料金の質問、" +
      "不具合報告、銀行・支店・郵便番号・駅・法人のデータの誤りや更新・掲載情報の修正・削除依頼、お礼、取材依頼など。",
    sales:
      "テラレンに何かを売り込む営業・宣伝・勧誘。自社製品・SaaS・アプリ・広告・SEO・記事制作・Web制作・人材・求人・営業代行・資金調達の提案、" +
      "相互リンクや被リンクの依頼、自社サイト・メディア・ポータルへの掲載や紹介の提案、業務提携の勧誘、商談やデモの日程調整依頼、配信停止リンク付きの一斉送信。",
    misdirected:
      "テラレンのサービスと無関係な、他社宛ての誤送信。通販の注文・返品・解約、届いた荷物、クレジットカードや自分の銀行口座の手続き、" +
      "振込や詐欺被害の相談、他社製品のサポート依頼など、テラレンが答えられない個人的な用件。",
    junk: "意味のない文字列、テスト投稿、アダルト・詐欺・フィッシング・リンクだけの投稿など、明らかなスパム。",
  },
};
const SPAM_THRESHOLD = 0.8; // sales + junk
const MISDIRECTED_THRESHOLD = 0.9;

呼び出し側。失敗したら null を返して、呼び出し元は「未判定」として扱います。

// Fails open: a missing key or a TypeSafe outage must not lose a real inquiry.
const classify = async (s, apiKey) => {
  try {
    const res = await fetch("https://api.typesafe.ai/v1/systemone", {
      method: "POST",
      headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
      body: JSON.stringify({
        model: "jev-latest",
        state: { category: s.category, name: s.name, email: s.email, message: s.message },
        questions: { kind: KIND_QUESTION },
      }),
      signal: AbortSignal.timeout(10_000),
    });
    if (!res.ok) return null;
    const { answers } = await res.json();
    return answers.kind.probabilities; // { inquiry, sales, misdirected, junk } 合計 1
  } catch {
    return null;
  }
};

判定部分はこれだけです。

const kind = TYPESAFE_API_KEY ? await classify({ category, name, email, message }, TYPESAFE_API_KEY) : null;
const spam = kind && kind.sales + kind.junk >= SPAM_THRESHOLD;
// StopForumSpam は IP が必須なので、IP が取れないときは自動報告も報告リンクも出さない
const report = ip ? { name, email, ip, message } : null;
if (spam && report && STOPFORUMSPAM_API_KEY) {
  context.waitUntil(reportToStopForumSpam(report, STOPFORUMSPAM_API_KEY));
}

LLM に「スパムなら true を返して」とプロンプトを書くのと違って、確率がそのまま閾値判定に使えるのが楽です。しきい値はコード側で決められるので、判定のロジックをプロンプトに埋め込まずに済みます。

検証データ#

Google フォーム時代から溜まっていたスプレッドシートで、response 列に私が手で付けた判定が入っています。

年別だと 2011〜2013 年が 10 件（昔やっていた 1TB レンタルサーバの問い合わせ）、2022 年以降が 175 件（ほぼ無料 API の問い合わせ）です。

ここで1つ誤算がありました。x はスパムという意味ではありませんでした。 「返信不要」くらいの意味で付けていたので、中身は以下が混ざっています。

• 営業
• 他社宛ての誤送信（Amazon の返品、カードや銀行の手続き、詐欺被害の相談など）
• 返信しなかった API の不具合報告やデータ修正依頼

なので「x を全部当てる」ではなく、「営業を全部拾えて、かつ正当な問い合わせを1件も営業にしない」を目標にしました。営業・誤送信・正当の3分類をするために4択にしたのはこれが理由です。

試行0：JevShield のデモ API#

最初は Jev を使ったスパム判定 SaaS の JevShield のデモ API で試しました。テキストしか渡せず、会社の業務内容を文脈として渡せません。しかも 10 リクエストで 429、94 件で日次上限に達しました。94 件での結果です。

営業っぽい 12 件は block 8（スコア 0.87〜0.99）、review 3、allow 1。日本語の営業そのものはちゃんと判定できています。ただ、誤送信はすべて allow で、会社の文脈を渡せないのでこれ以上詰められません。そこで TypeSafe の System One API を直接叩くことにしました。

試行1：System One で4択#

上のコードとほぼ同じ構成で、181 件を4並列で投げて 9.57 秒、エラー 0 でした。

外したのはこういうものでした。

• 相互リンク・ポータル掲載の依頼が inquiry になる（inquiry 0.51〜0.64）。丁寧な文面なので問い合わせっぽく見える。そもそも最初の criteria に「個人ブログからの紹介や相互リンクの相談」を inquiry として書いていたのが悪い
• 2012 年のレンタルサーバの質問が misdirected になる（0.53〜0.95）。今のサイト説明にレンタルサーバが出てこないので当然
• 2011 年の「アダルトコンテンツを置いてもいいか」という質問が junk（0.59）

難しいのは日本語ではなく、カテゴリの境界でした。

試行2：criteria の書き方を直す#

• inquiry に「自社サービス（API・データ）の使い方・エラー・仕様・利用条件・料金の質問」「データの誤り・更新・削除依頼」「お礼」を追加
• sales に「求人」「相互リンクや被リンクの依頼」「自社サイト・メディア・ポータルへの掲載や紹介の提案」を追加
• misdirected を「テラレンが答えられない個人的な用件」に絞る

表だけ見ると大差ないですが、sales + junk の確率の分布を見ると綺麗に割れています。

0.35 と 0.94 の間に1件もありません。 しきい値を 0.8 にしたのは、両側に十分な余白があるからです。

29 件のうち 7 件は手ラベルが o（返信した）でした。中身は API 掲載の打ち合わせ依頼、ゲームメディア、SEO コンテンツ制作、リーガルテック、車買取サイトの相互リンク、学生インターンの求人サイト、個人ブログの記事紹介依頼（0.96）。当時は律儀に返信していたというだけで、どれも売り込みです。個人ブログの紹介依頼はグレーですが、送られてくる側としては営業と変わらないので良しとしました。

他社宛ての誤送信を報告しない理由#

misdirected が 0.97 以上のものは 45 件あり、ほとんど本当に他社宛てでした。ただ、正当な問い合わせでも misdirected が高く出るものがあります。

それに、他社宛てに送ってしまう人は困っている一般の人です。StopForumSpam は公開データベースなので、ここに載せるのは筋が悪い。なので misdirected は件名に 【他社宛て?】 を付けるだけにしました。

ちなみに TypeSafe のドキュメントにも「英語が主要な学習言語で、CJK も扱えるが同じ精度ではないので自分のデータで試すこと」と書いてあります。今回の範囲では、日本語の営業文は JevShield でも System One でも 0.87〜1.00 で取れていて、言語の問題は感じませんでした。

本番相当でのスモークテスト#

Turnstile・Resend・StopForumSpam をスタブにして、本物のハンドラから本物の TypeSafe を呼んだ結果です。4 件で 0.96 秒でした。

サーバに何も保存しない#

リンクの t には、StopForumSpam に送る情報（名前・メールアドレス・IP・本文の先頭 1,000 文字）と発行時刻をそのまま入れて、HMAC-SHA256 で署名しています。

base64url(JSON payload) "." base64url(HMAC-SHA256(payload))

export const signReportToken = async (r: SpamReport, secret: string, now = Date.now()) => {
  const payload: TokenPayload = {
    name: r.name,
    email: r.email,
    ip: r.ip,
    // Only the evidence StopForumSpam accepts; keeps the link short.
    message: r.message.slice(0, EVIDENCE_LIMIT),
    iat: now,
  };
  const body = encoder.encode(JSON.stringify(payload));
  const signature = await crypto.subtle.sign("HMAC", await hmacKey(secret), body);
  return `${toBase64Url(body)}.${toBase64Url(new Uint8Array(signature))}`;
};

• 署名があるので、第三者が勝手に報告リンクを作れない
• 有効期限 30 日。転送されたり漏れたりしたメールからの再利用を制限する
• Web Crypto API だけで完結するので、Workers の KV や D1 は不要
• 中身は暗号化ではなく署名だけなので、リンクを base64 デコードすれば読めます。ただ同じ内容はメール本文にも書いてあるので、ここは割り切りです

GET では報告しない#

リンクを開くと確認ページが出るだけで、「報告する」ボタンの POST で初めて報告します。

sequenceDiagram
participant M as Gmail（私）
participant F as /api/spam-report
participant S as StopForumSpam
M->>F: GET ?t=token
F->>F: HMAC 検証・30日以内か
F-->>M: 確認ページ（名前・メール・IP・本文と「報告する」ボタン）
M->>F: POST t=token
F->>F: もう一度検証
F->>S: POST /add（username, email, ip_addr, evidence）
S-->>F: 200
F-->>M: 報告しました

理由はメールのセキュリティスキャナがリンクを先読みするからです。GET で報告してしまうと、メールが届いた瞬間にスキャナが踏んで、本物の問い合わせ客を公開データベースに載せてしまいます。確認ページには Content-Security-Policy: default-src 'none'、Cache-Control: no-store、Referrer-Policy: no-referrer を付けて、表示する値はすべて HTML エスケープしています。

StopForumSpam の API キーが reportable になっていなかった#

上で例に出した健康管理サービスの営業は、ちゃんと sales 1.00 で [SPAM] が付いていました。ところが StopForumSpam を検索すると、メールアドレスも IP も appears: 0。自動報告が登録されていませんでした。

StopForumSpam の API キーには「報告に使えるかどうか」の設定があって、それが有効になっていなかったのが原因でした（古い Functions のログが残っていなかったので推定です）。設定を直して手動で報告したら、20〜90 秒後に appears: 1 になりました。/add の結果は waitUntil の中でログに出すだけなので、失敗しても誰も気付かないのが弱いところです。

報告に必要な IP がメールに書いていない#

手動報告しようとしたら、IP がメールに書いていないことに気付きました。Cloudflare の GraphQL Analytics API で /api/contact への POST を引いて、受信時刻と分単位で突き合わせて IP を割り出しました。ちなみにこのとき、約 4.5 週間で 200 を返した POST は3件だけで、残りの 400 はほぼ Tor とオランダのホスティングからでした。Turnstile はちゃんと仕事をしています。今は報告リンクのトークンに IP も入れているので、この突き合わせは不要になりました。

Pages の secret は再デプロイしないと反映されない#

wrangler pages secret put で SPAM_REPORT_SECRET を入れても、今動いているデプロイには反映されません。次のデプロイから効きます。Preview 環境には STOPFORUMSPAM_API_KEY を入れていないので、Preview では報告リンクが出ません。

マージのタイミングで 11 分間スパムを捨てていた#

最初の「スパムは捨てる」コミットの時点で PR がマージされてしまい、「[SPAM] を付けて送る」コミットが入るまでの約 11 分間、本番はスパムを捨てていました。捨てたスパムは Pages のログにしか残らず、そのログもすぐ消えます。メールで全部送る方針にしておいて正解でした。

StopForumSpam のルールとの関係#

StopForumSpam の FAQ には次のように書いてあります。

Spam submission must be triggered by a human who makes the decision to report each incident using some judgment. If it was a decision that could be made automatically by software there would be no need for this database.

つまり報告は人間が1件ずつ判断して行うものという建前です。メールアドレスについても「登録時にメール認証をしていないなら送ってはいけない」とあります。お問い合わせフォームにメール認証はありません。

本来は手動で報告しないといけないんですね。。。今の自動報告は、この文面とは正直ぶつかっています。

とはいえ、しきい値の上下には 0.35〜0.94 という大きな余白があって、過去データでは正当な問い合わせを営業と判定したものはありませんでした。なので自動報告は続けて、その代わり誤報告（false positive）が出たらちゃんと直す運用にしています。

• [SPAM] ラベルのメールは受信トレイをスキップするだけで、定期的に目を通す
• 本物の問い合わせが混ざっていたら、My Spammers から該当の報告をすぐ削除する
• 見逃し（false negative）は、報告リンクから目で見て報告する

配布済みのリストからは消せないので、削除はとにかく早くやるのが大事です。

jev-latest を使っている#

jev-latest はエイリアスで、現時点では jev-1.13.0 を指しています。ドキュメントには「しきい値をあるバージョンに合わせて調整したなら、エイリアスではなくバージョン ID を指定して」と書いてあります。今回の 0.8 は 1.13.0 で検証した値です。

ただ、あえて jev-latest のままにしています。営業とそれ以外は 0.35 と 0.94 の間で大きく割れているので、多少確率がずれても判定は変わらないはずです。それより新しいモデルの改善（特に日本語）を自動で受け取れるほうがうれしい。レスポンスの model には実際に答えたバージョン ID が入るので、下の usage と一緒にログに出しておけば、おかしくなったときに追えます。

usage をログに出していない#

レスポンスには usage.input_tokens が返ってくるので、ログに出しておけばコストの推定ではなく実測値が出せます。