every Tech Blog

株式会社エブリーのTech Blogです。

個人情報だらけのECサイトの新規開発をClaudeに任せるためにやったこと

はじめに

こんにちは、エブリーでECの開発をしている山舗です。

この度、弊社で運営している EC サイトにて、既存の SaaS のカートに代わる自社実装を新規に開発し、全面リプレイスを行いました。扱うデータには、会員の個人情報や、定期購入の課金情報などがあります。期間は 3 か月弱、コードは約 61 万行、コミットは約 7,500 件に及ぶ開発となりました。この規模の開発を短期間で行うには、Claude Code を中心に、半自律的に開発を進めさせる必要がありました。

一方で、世の中では個人情報の漏えいのニュースが数多く流れています。2025 年に上場企業とその子会社が公表した分だけで、3,063 万人分に及びます(東京商工リサーチの調査)。

この記事では、こうした状況の中で、Claude に書かせる前提で開発しながら個人情報を守るために、どんな技術を選び、どう使ったかをご紹介します。

1. Claude に書かせる前提の技術選定

新規開発にあたって、まず技術選定から始めました。開発の中心を Claude に任せるので、Claude が書いたコードに読み違いや書き忘れがあっても、実行する前に機械で見つけられることを基準にしました。選んだ構成は次のとおりです。

役割 選んだ技術
言語 TypeScript(フロント / バックエンド)
API Hono
DB と ORM PostgreSQL、Drizzle
フロント(storefront) Next.js、Tailwind
フロント(admin) Vite、Tailwind

まず、言語は TypeScript に統一しました。バックエンドを Go、フロントを TypeScript のように分けると、2 つの言語の間で型は自動ではつながりません。API の形を OpenAPI などの中間の定義に書き、そこからフロントの型とクライアントを生成する工程が要ります。例えば、「定期購入の配送サイクルは、決まった日数のどれか」のような値の決まりも、バックエンドの検証と画面の検証の 2 か所に書くことになります。片方だけ直すと、もう片方は古いまま動き、ずれに気付くのは実行したときです。

AI は、API だけを直して画面を直し忘れるといった、片方だけの変更をよく書きます。それが実行時まで見つからない作りは避けたかったので、API から画面までを 1 つの言語にして、型をつなげることにしました。フロントとバックエンドでドメインのロジックを共有でき、lint とコーディングの決まりを 1 言語に絞れるのも理由です。

その型を API から画面へ届けるために、API のフレームワークには Hono を選びました。Hono RPC の型推論を使うと、API の定義からフロントの呼び出しまで、型がそのままつながります。Express などより軽く、Web 以外から使う API も今は無いので、これで足りました。NestJS は DI の構造が複雑で、問題に起動時にしか気付けません。構造を静的に追えるほうが AI に向くと考えました。

DB の側も同じ考え方で、ORM には Drizzle を選びました。スキーマを TypeScript で定義し、型をそこから導くので、独自の言語やコード生成の工程がありません。Prisma は独自の言語でスキーマを書き、クライアントの生成が要ります。行ロックと入れ子のトランザクションを API で書けることも理由で、これは後で例を挙げます。管理画面の見た目には Tailwindを使っています。Tailwind は任意の値を text-[#e91e63] のように角括弧で書くので、AI が決まったスタイルから外れたことを機械で検知しやすくなります。

// 決めた色のトークンを使った書き方
<button className="bg-primary">申し込む</button>

// 決まりから外れた書き方。角括弧があるので、検索で見つかる
<button className="bg-[#0b794d]">申し込む</button>

色は決めたトークンだけを使う決まりにしていて、-[# で検索すれば、外れた箇所を一覧にできます。

型を一貫させたときに起きること

この EC サイトでは、配送サイクルの決まりは 1 か所にしかありません。

// packages/domain-values/src/subscription.ts(抜粋)
export const cycleDaysSchema = z.union([z.literal(7), z.literal(14), z.literal(21), z.literal(28)]);

export type CycleDays = z.infer<typeof cycleDaysSchema>;

この 1 つの定義を、次の全部が参照します。

  • DB から読んだ値の検査(repository)
  • API の要求と応答の契約(contracts)
  • 画面のコード(ストアフロントと管理画面)

API のルートの型は、Hono RPC でフロントのクライアント(hc<AppType>)にそのまま届きます。そのため、API の応答の項目を変えると、それを使う画面のコードが型の検査で落ちます。直し忘れは、実行する前に CI で止まります。実際にあった例を 2 つ紹介します。

例 1: 型を変えた後の直し忘れが、8 つのファイルで見つかった

顧客のメールアドレスは、最初はただの string でした。これを、前後の空白を取り、形式を確かめ、小文字にそろえた値だけが入る型に変えました。

// packages/domain-values/src/email.ts(抜粋)
export const emailAddressSchema = z
  .string()
  .trim()
  .pipe(z.email())
  .transform((value) => value.toLowerCase())
  .brand<"EmailAddress">();

export type EmailAddress = z.infer<typeof emailAddressSchema>;

.brand を付けた型には、このスキーマを通した値しか入りません。ただの文字列を渡すと、型の検査で落ちます。

この変更を進めている間に、main ではメールアドレスを文字列のまま渡すテストが足されていました。main を取り込んで型の検査を流すと、API・画面・ドメインの 3 つのパッケージに散った 7 つのテストが落ちました。直し方はどれも同じです。

// 直す前: 型の検査で落ちる
customerContact={{ email: "member@example.com", phone: null }}

// 直した後
customerContact={{ email: emailAddressSchema.parse("member@example.com"), phone: null }}

型が無ければ、検証を通していない値が渡っていることに気付く手がかりがありません。型の検査は、直す場所をファイルと行で全部挙げます。

例 2: 画面に届く応答の型が広がっていたのを直し、型だけのテストで固定した

管理画面の API には、URL の番号の形式が合わないときに 404 を返す共通の部品があります。この部品が応答を { error: string } で受けていたため、エラーのコードの型が string に広がっていました。Hono RPC は応答の型をそのまま画面に届けるので、画面の側では、どのコードが返るのかが型から分からなくなっていました。

// apps/admin-api/src/middleware/validation.ts(抜粋)

// 直す前
export function codeParamValidator<Schema extends ZodType>(
  schema: Schema,
  notFound: { error: string },
) { /* ... */ }

// 直した後: 渡されたコードをリテラル型のまま保つ
export function codeParamValidator<
  Schema extends ZodType,
  const NotFound extends { error: string },
>(schema: Schema, notFound: NotFound) { /* ... */ }

同じことがまた起きたら型の検査で落ちるように、画面の側に、型だけを確かめるテストを足しました。実行時には何もしないテストです。

// apps/admin/src/lib/api-client.test.ts(抜粋)
expectTypeOf<
  InferResponseType<(typeof apiClient.customers)[":code"]["withdrawal"]["$post"], 404>
>().toEqualTypeOf<{ readonly error: "customer_not_found" }>();

API の側でこの応答の型が変わると、画面の側のこのテストが型の検査で落ちます。

行ロックと入れ子のトランザクションを使う場面

ORM に Drizzle を選んだ理由の 1 つは、行ロックと入れ子のトランザクション(savepoint)を API で書けることです。EC では、同じデータに 2 つの操作が重なる場面が多くあります。

たとえば、会員がクーポンコードを入れた瞬間に、管理者がそのクーポンを停止することがあります。「使えるか」を確かめてから会員の保有を作るまでの間に停止が入ると、停止されたクーポンが会員の手元に残ります。そこで、クーポンの行をロックして読み、判定と保有の作成を同じトランザクションで済ませます。

// packages/repositories/src/coupons/coupon-code-entry.ts(抜粋)
const query = executor
  .select({ id: coupons.id, grantOnly: coupons.grantOnly })
  .from(coupons)
  .where(sql`${coupons.code} COLLATE "C" = ${code}`)
  .limit(1);
const [row] = await (options?.forUpdate === true ? query.for("share") : query);

ロックはクエリの最後に .for("share") を付けるだけで、row の型は select に書いた列から決まります。一方、Prisma のクエリの API には行ロックの指定がありません(要望の issue は 2021 年から開いたままです)。同じことをするには、生の SQL を書くことになります。

// Prisma で同じ読み取りを書く場合の例(実際のコードではありません)
const rows = await tx.$queryRaw<CouponRow[]>`
  SELECT id, grant_only FROM coupons WHERE code = ${code} FOR SHARE
`;

CouponRow は自分で書いた型で、SQL が返す列と合っているかは検査されません。列の名前を変えても型の検査では落ちず、実行して初めて失敗します。行ロックを取る読み取りはリポジトリの中に 50 か所ほどあるので、そこで型が途切れないことを重視しました。

この上に、機械で確かめる決まりを重ねています。規約には「ルールは機械で守れるものから機械化する。散文の規約は機械化できないものに限る」と書いてあります。

  • パッケージの依存の向きは、Turborepo の boundaries が CI で確かめる。顧客向けの API と社内向けの API は、互いを import できない
  • id は、どの表の id かを型で区別する(Zod の brand)。注文の id を顧客の id として渡すと型エラーになる
  • 外部に触れる部品には、手書きのフェイクと本物の両方に同じテスト(契約テスト)を流し、挙動のずれを見つける

2. その型で個人情報を守る

個人情報も、「気を付ける」ではなく「書き忘れたら通らない」形に寄せました。

列を足したら、分析基盤に出すかを決めないと通らない

全部の表の全部の列を、全社のデータ基盤(Databricks)に「出す」か「出さない」かに分けた定義を、コードに置いています。分類の型を Drizzle の表の定義から導いているので、列を足して分類を書き忘れると型の検査で落ちます。表を足して書き忘れるとテストで落ちます。

// packages/db/src/analytics-exposure.ts(抜粋)
export type Exposure = "analytics" | "restricted";

type ColumnExposure<T extends PgTable> = { [K in keyof T["_"]["columns"]]: Exposure };

デプロイのたびに、マイグレーションの後で、データ基盤用の DB のユーザーの権限を全部外し、「出す」列だけに列単位で付け直します。分類と実際の権限が食い違ったまま残りません。個人情報は DB の権限で守られるので、取り込みのコードを通さずに DB を読んでも取れません。

この仕組みは、入れた PR の中でさっそく働きました。main を取り込んだところ、別の PR が足した 3 つの列の分類が無く、型の検査が落ちました。一方で、型では止まらない誤りもレビューで見つかっています。サポート担当が自由記述する列(返金の理由など)が「出す」側に分類されていました。自由記述には顧客の名前や電話でのやり取りが書かれうるので、書く人が誰でも「出さない」にする決まりを足しました。

監査ログに、個人情報の写しを増やさない

管理画面の変更履歴の元になる監査ログも、同じ作りです。全部の列を「前後の値を書く」「書かない」「値を記録せず、変わったことだけ書く」などに分類し、漏れは型とテストで止まります。カードの下 4 桁と有効期限は、値を {"unrecorded": true} に差し替えて記録します。アプリの DB ユーザーは、監査ログに追記しかできません。書き換えと削除の権限を、デプロイのたびに外しています。

エラーの監視には、送る前に止める

Sentry の SDK は、何も指定しないと、利用者の情報・Cookie・要求の本文・DB の引数・ローカル変数を集めます。これを止める設定を 1 か所に置き、どのアプリの初期化もそれを使います。届いてから Sentry の側で消す案は、個人情報が一度届いてしまうので採りませんでした。

ログでも同じ考え方を取っています。倉庫のシステムの API が JSON として読めない応答を返したときに、本文の先頭 500 文字を例外のメッセージに入れていたことがありました。受注や出荷の伝票の応答が壊れた形で返ると、宛先の氏名や住所がログに出ます。Claude に差分を分析させたレビューで見つかり、例外に入れるのを状態コード・種類・本文の長さだけに直しました。

id から、他人のデータを順にたどれないようにする

表の id は連番でなく UUIDv7 にしています。連番の id が URL や API に出ると、番号を 1 つずつ変えて他人の注文やお届け先を順に試せます。番号の大きさから、会員や注文の件数も読めます。UUIDv7 なら、この列挙と件数の推測が難しくなります。

ただし、id を認可の代わりにはしていません。誰のデータかの確認は別に必ず行い、他の会員のデータを指す要求には 403 でなく 404 を返して、その id があるかどうかも分からないようにしています。Claude に読ませる規約にも「外に出る識別子に、連番を新しく使わない」と書いてあります。UUIDv7 は作った時刻を含むので、時刻を知られて困るデータには別の形式を検討する決まりです。

そもそも持たないもの

カード番号とセキュリティコードの入力欄は、Stripe の Payment Element をそのまま使っています。入力された値は Stripe に直接送られるので、自社のコード・ログ・DB を通りません。会員のパスワードはCognito に渡し、自社の DB には持ちません。この考え方は「個人情報を自社のDBに持たない設計は、どこまでできるのか - every Tech Blog」に詳しく書かれています。

3. そのほかにやったこと

型とテストで確かめられるのは、形にできた決まりだけです。そのほかに、次のようなこともしています。

Claude Code が読む規約(AGENTS.md)には、個人情報の扱いで守ることを書いています。個人情報をログや監視に出さない、渡す相手は一覧にある相手だけにする、他の会員のデータを指す要求には 403 でなく 404 を返す、外に出る識別子に連番を使わない、といった内容です。Claude Code のセキュリティレビューのプラグインも入れていて、「境界は会員個人にある」といった、このサービス固有の観点を渡しています。認証・認可・決済の境界に触る変更は、人のレビューを必ず通します。

規約そのものが実態とずれていたこともあります。以前の規約は「個人情報をログ・監視・外部 SaaS に平文で出さない」でした。しかし実際には、倉庫には宛先の氏名・住所・電話番号を、決済代行には請求先の氏名を渡しています。そこで「外部に渡すのは業務に要る相手だけ」として渡してよい相手の一覧を書き、相手を足すときはその行を直してレビューを受ける形にしました。

まとめ

今回は、EC サイトの新規開発で、Claude を中心に開発を進めるために選んだ技術と、その上で個人情報を守るためにしたことを紹介しました。

言語を TypeScript に統一し、Hono と Drizzle で DB から画面まで型をつなげたことで、Claude が書いたコードの直し忘れを、動かす前に型の検査で見つけられるようになりました。個人情報についても、分析基盤に出す列や監査ログに残す値を型とテストで確かめる形にして、書き忘れたら通らないようにしています。型で確かめられない部分は、Claude に読ませる規約とセキュリティレビュー、人のレビューで補っています。

私自身、新卒エンジニアとして入社半年でここまでの仕事を任せていただけるとは夢にも思っていませんでしたが、手でコードを書いていたときとは違った角度で技術そのものの強みや使いどころについて理解を深められ、良い機会になりました。型やテスト、DB の権限のように、AI に書かせる今だからこそ効いてくる仕組みのありがたさを、実際に作りながら感じました。

AI を中心に開発を進めようとしている方や、個人情報を扱うサービスを作っている方の参考になれば幸いです。

最後までお読みいただきありがとうございました!

ターミナルソフトは何をしているのか

開発2部の内原です。

自分の観測範囲では、最近Claude CodeやCodex CLI、Gemini CLIといったAIツールのCLIを使うケースが増え、以前に比べてターミナルソフトを使う機会が多くなったように感じます。

ただ、日常的に使っているとしても、このソフトウェアが何をしているかを正しく理解しているとは言えない状態でした。ターミナル、シェル、ttyの区別が曖昧だったり、Ctrl-Cでプログラムが停止するのはなぜか、文字の色付けは誰が担当しているのか、といったことを人に説明できるだけの知識は持てていないという自覚がありました。

そこでこの記事では、ターミナルソフトの挙動について改めて学んでみます。

なお、ターミナルソフトは本来MacやWindows上で動作するGUIアプリケーションとして実装されるものですが、今回の目的はあくまで内部の挙動の把握であるため、描画やフォントといったGUI部分は扱わず、その裏側の機構のみを対象とします。POSIX環境を前提に、C言語で動作を確かめる方針です。

用語の整理

まず、ターミナルを使っているときに関わってくる要素を整理します。

  • ターミナルエミュレータ
    • 普段ターミナルソフトと呼んでいるGUIアプリケーション
    • キー入力の受付と画面の描画を担当
  • pty(擬似端末、pseudo tty)
    • カーネルが提供する、双方向なバイト列のやり取りに用いられる仕組み
    • masterとslaveの2つの終端を持ち、master側にターミナルエミュレータ、slave側にシェルがそれぞれ接続される
  • カーネル内の端末処理層(line discipline)
    • ptyのmasterとslaveの間に位置する加工層
    • 行編集、エコー、シグナル生成などを担当
  • シェルや各プログラム
    • ptyのslaveを標準入出力として読み書きする

データの流れを図にすると以下のようになります。

ターミナルのデータの流れ

両端のターミナルエミュレータとシェルはユーザー空間のプロセスで、その間のptyとline disciplineはカーネル内に存在します。

ttyという名前はteletypewriterに由来します。かつてはコンピュータにシリアル回線で物理的な端末(VT100など)を接続しており、カーネルはその回線の先にいる端末とのやりとりをttyとして扱っていました。物理端末の役割をソフトウェアで再現したものがターミナルエミュレータで、シリアル回線の代わりを務めるのがptyです。

自分のシェルがどの端末につながっているかはttyコマンドで確認できます。

$ tty
/dev/ttys003

psでTTY列を表示すると、プロセスと端末の対応が見えます。

$ ps -o pid,tty,comm
  PID TTY      COMM
 1029 ttys000  -zsh
14861 ttys000  tmux
 1041 ttys001  -zsh
43561 ttys008  vim

ターミナルのウィンドウやタブ、tmuxのペインごとに、別々のptyが割り当てられていることがわかります。

ptyを開いてシェルを実行

ターミナルエミュレータの中核は、ptyを確保してシェルを起動し、そのあとはバイト列を中継し続けることです。

以下のminipty.cは、script(1)コマンドとほぼ同じ動作をする、画面描画を持たない簡易的なターミナルの実装です。GUI部分こそ存在しませんが、ターミナルソフトとやっていること自体は同じと言えます。

#define _GNU_SOURCE
#include <fcntl.h>
#include <poll.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/ioctl.h>
#include <termios.h>
#include <unistd.h>

static struct termios orig;

static void restore(void) { tcsetattr(STDIN_FILENO, TCSANOW, &orig); }

int main(void) {
    // 1. ptyのmasterを確保し、対応するslaveのパスを取得
    int master = posix_openpt(O_RDWR | O_NOCTTY);
    grantpt(master);
    unlockpt(master);
    char *slave_name = ptsname(master);

    pid_t pid = fork();
    if (pid == 0) {
        // 2. 子:新しいセッションを生成し、slaveを制御端末にしてfd 0,1,2に接続
        setsid();
        int slave = open(slave_name, O_RDWR);
        ioctl(slave, TIOCSCTTY, 0);
        dup2(slave, 0);
        dup2(slave, 1);
        dup2(slave, 2);
        close(slave);
        close(master);
        execl("/bin/sh", "sh", NULL);
        _exit(1);
    }

    // 3. 親:自分の端末をrawモードに変更し、キー入力を加工なしで素通しする
    if (isatty(STDIN_FILENO)) {
        tcgetattr(STDIN_FILENO, &orig);
        atexit(restore); // 終了時に元の設定へ戻す
        struct termios raw = orig;
        cfmakeraw(&raw);
        tcsetattr(STDIN_FILENO, TCSANOW, &raw);
    }

    // 4. 親:「キーボード → master」「master → 画面」の中継をくり返すのみ
    struct pollfd fds[] = {{STDIN_FILENO, POLLIN, 0}, {master, POLLIN, 0}};
    char buf[4096];
    for (;;) {
        poll(fds, 2, -1);
        if (fds[0].revents & POLLIN) {
            ssize_t n = read(STDIN_FILENO, buf, sizeof buf);
            if (n <= 0) fds[0].fd = -1; // 入力が尽きたら以降は監視しない
            else write(master, buf, n);
        }
        if (fds[1].revents & (POLLIN | POLLHUP)) {
            ssize_t n = read(master, buf, sizeof buf);
            if (n <= 0) break; // シェルが終了した
            write(STDOUT_FILENO, buf, n);
        }
    }
    return 0;
}

説明のため、エラー処理は省略しています。処理は大きく4つに分かれます。

  • ptyの確保
    • posix_openpt(3)でmasterを開く
    • grantpt(3)とunlockpt(3)で、対応するslaveを使用可能にする
    • ptsname(3)でslaveのデバイスパス(/dev/ttys005など)を取得
  • 子プロセスの準備
    • setsid(2)で新しいセッションを作成し、元の端末から切り離す
    • slaveを開いて制御端末にする
    • dup2(2)でslaveをfd 0, 1, 2に複製してから、execl(3)でシェルを起動
  • 親プロセスの端末設定
    • 自分自身の端末をrawモードに設定
  • 中継
    • poll(2)で2つのfdを監視し、キーボードから来たバイト列はmasterへ、masterから来たバイト列は画面へ書き出す

dup2(2)による複製は、以前の記事で扱ったリダイレクトと同じ仕組みです。

準備が終わった時点で、fdは以下のような状態になっています。

minipty実行時のfdの接続

実行して、子のシェルでttyを打ってみます。

$ tty
/dev/ttys003
$ cc minipty.c -o minipty && ./minipty
sh-3.2$ tty
/dev/ttys005
sh-3.2$ exit
exit
$

子のシェルは、元の端末(/dev/ttys003)とは別のpty(/dev/ttys005)につながっています。

親プロセスの処理は、2つのfdの間でバイト列を転送しているだけです。プロンプトの表示も、打った文字が画面に出るのも、シェルや次の章で扱うline disciplineの仕事であるため、このプログラム自体はデータの中身を一切解釈していません。

GUIのターミナルソフトは、この中継部分の画面側を自前の描画に置き換えたものだと考えることができます。

line disciplineとtermios

ptyのmasterとslaveの間には、line disciplineという加工層が存在しています。普段は意識しませんが、ターミナルの基本的な挙動の多くはここで実現されています。

line disciplineの処理

現在の設定はstty -aで確認できます。以下はmacOSでの出力の抜粋です。

$ stty -a
lflags: icanon isig iexten echo echoe -echok echoke -echonl echoctl
iflags: -istrip icrnl -inlcr -igncr ixon -ixoff ixany imaxbel -iutf8
oflags: opost onlcr -oxtabs -onocr -onlret
cchars: discard = ^O; dsusp = ^Y; eof = ^D; eol = <undef>;
    eol2 = <undef>; erase = ^?; intr = ^C; kill = ^U; lnext = ^V;
    ...

主な項目の意味は以下のとおりです。

  • icanon
    • canonicalモード
    • 入力を行単位で蓄積し、Enterが押された時点でプログラムに渡す
    • Backspaceによる削除もこの段階で処理される
  • echo
    • 受け取った文字をmaster側へ送り返して画面に表示する
  • isig
    • intr = ^Cなどの特殊文字を受け取ったら、シグナルを生成する
    • Ctrl-Cを押したとき、ターミナルソフトは0x03の1バイトを送るだけ
    • line disciplineがそれをSIGINTに変換し、フォアグラウンドのプロセスに送ることでプログラムが停止する
  • onlcr
    • 出力の改行\nを\r\nに変換する

rawモード

vimやless、AIツールのCLIのようなTUIアプリケーションは、line disciplineの加工をほとんど無効にしたrawモードで動作しています。1キーごとに反応し、カーソル移動や補完、エコーの表示方法を自前で制御する必要があるためです。

line disciplineの設定はtermios構造体で表され、tcgetattr(3)とtcsetattr(3)で読み書きします。cfmakeraw(3)を使うと、icanon、echo、isigなどの加工をまとめて無効にできます。

前章のプログラムで親プロセスが自分の端末をrawモードにしていたのも同じ理由です。このプログラムではline disciplineが2つ直列に並んでいます。

  • 親プロセスと本物の端末の間のline discipline
  • masterとslaveの間のline discipline(子のシェル側)

親側をrawモードにしないと、Ctrl-Cは親側のline disciplineでSIGINTに変換され、子のシェルではなく親自身が終了してしまいますし、エコーも二重になります。親側をrawにして素通しすることで、加工は子のシェル側のline disciplineだけが担当するようになります。

エスケープシーケンス

line disciplineを通過した出力は、最終的にターミナルソフトに単なるバイト列として届きます。

文字の色やカーソルの移動は、バイト列の中に埋め込まれた制御用の文字列、エスケープシーケンスによって実現されています。

以下のコマンドでは赤文字でredという文字が出力されます。

$ printf '\e[31mred\e[0m\n'

ESC(\e)、[、数字、終端文字、で命令を表します。

上の例ではESC [31mで文字色を赤にし、ESC [0mで装飾を元に戻しています。

以下はよく使われるエスケープシーケンスです。

シーケンス 意味
ESC [31m 文字色を赤に設定
ESC [0m 装飾をリセット
ESC [2J 画面全体を消去
ESC [5;10H カーソルを5行10列目に移動
ESC [A カーソルを1行上に移動

ターミナルソフト側の処理

ターミナルソフトは、受け取ったバイト列を状態機械によってパースし、画面バッファを更新しています。

ターミナルソフトの出力処理

  • パーサ
    • 通常の文字を受け取ったら、カーソル位置のセルに書き込んでカーソルを進める
    • ESCを受け取ったら、エスケープシーケンスの読み取り状態に遷移
    • [に続く数字をパラメータとして蓄積し、終端文字(m、H、Jなど)を受け取った時点で命令を実行
  • 画面バッファ
    • 行数 × 列数のセルの配列
    • 各セルは文字と属性(文字色、背景色、太字など)を保持
  • 描画
    • 画面バッファの内容をフォントで描画する(今回は対象外)

TERMとterminfo

エスケープシーケンスは端末の種類によって異なる場合があります。そこでvimやless、AIツールのCLIのようにシーケンスを出力する側のプログラムは、環境変数TERMで出力先の端末の種類を知ります。vimやlessは、さらにterminfoというデータベースから対応するシーケンスを引いています。

TERM自体は、ターミナルソフトがシェルを起動する際に自身の端末種類を伝えるために設定しておくものです。

$ echo $TERM
xterm-256color
$ infocmp xterm-256color
    ...
    clear=\E[H\E[2J,
    cup=\E[%i%p1%d;%p2%dH,
    ...

clearは画面消去、cupはカーソル移動、などを表しています。

なおncursesなどの端末用ライブラリを利用すればこの定義を自動的に参照してくれるため、アプリケーション側でシーケンスを直接記述することを避けられます。

isattyとパイプ

ここまでは、プログラムの標準入出力が端末につながっている場合の話でした。しかし標準出力の行き先はパイプやファイルの場合もあり、多くのプログラムは出力先が端末かどうかで挙動を変えています。

判定にはisatty(3)を使います。

#include <stdio.h>
#include <unistd.h>

int main(void) {
    if (isatty(STDOUT_FILENO)) {
        printf("\033[32mstdout is a terminal\033[0m\n");
    } else {
        printf("stdout is NOT a terminal\n");
    }
    printf("line 1\n");
    sleep(2); // 端末なら1行ずつ、パイプならまとめて出力されることを確認するための待機
    printf("line 2\n");
    return 0;
}

同じプログラムを3通りの方法で実行してみます。

$ ./isatty_demo
stdout is a terminal
line 1
line 2

$ ./isatty_demo | cat
stdout is NOT a terminal
line 1
line 2

$ ./minipty
sh-3.2$ ./isatty_demo | cat
stdout is NOT a terminal
...
sh-3.2$ ./isatty_demo
stdout is a terminal
...

端末に直接出力すると緑色で表示され、| catを付与すると色付けはなくなります。前述のminiptyの中で実行した場合も、子のシェルの標準出力はpty slaveなので端末として判定されます。

ls --color=autoやgitも同じように判定しています。

  • ls --color=auto
    • 端末に出力するときだけ色を付ける
  • git logなど
    • 端末に出力するときはページャ(less等)を起動し、パイプ先では起動しない

AIエージェントがコマンドを実行するとき

この挙動は、AIエージェントにコマンドを実行させるときにも関わってきます。

試しにClaude Codeにttyと、シェル自身の標準入出力を確認するコマンドを実行させてみました。

$ tty
not a tty
$ lsof -p $$ -a -d 0-2
COMMAND PID           USER   FD   TYPE DEVICE SIZE/OFF    NODE NAME
zsh     549       uchihara    0r   CHR    3,2      0t0     336 /dev/null
zsh     549       uchihara    1w   REG   1,14       18 8392275 /private/tmp/claude-502/.../tasks/bryiflukh.output
zsh     549       uchihara    2w   REG   1,14       18 8392275 /private/tmp/claude-502/.../tasks/bryiflukh.output

自分の環境では、標準入力は/dev/null、標準出力と標準エラー出力はファイルに接続されており、ptyは使われていませんでした。このため、端末上で人間が実行した場合とは以下のような違いが生じます。

  • 色付けが行われない
    • isatty(3)が偽になるため、lsやgitはカラー無効とする
  • 出力が一括で行われる
    • 行単位ではなくブロック単位でバッファリングされる
    • 時間のかかるスクリプトの途中経過が見えないことがある
  • 対話的なコマンドは利用不可能
    • 標準入力が/dev/nullに接続されているので、入力を求めるコマンドはすぐにEOFを受け取って終了する
    • パスワード入力のように/dev/ttyを直接開くコマンドは、制御端末がないため失敗する
    • 標準入力がパイプのまま開いている実装では、入力を待ち続けて固まることがある

まとめ

ターミナルソフトが担当しているのは、以下の処理でした。

  • pty masterの読み書き
  • キー入力をバイト列に変換してmasterに書き込む
  • masterから届いたバイト列のエスケープシーケンスを解釈して描画する

それ以外の、行編集やエコー、Ctrl-Cによるプロセスの停止はカーネルのline disciplineが、コマンドの解釈はシェルが担当しています。日常的に使っているターミナルソフトも、中身は数十行のCで再現できる程度の単純な機構の組み合わせであることがわかりました。

新しい Siri にレシピを出したかったインターンの話

App Intents を使った機能の組み込み

目次

はじめに

こんにちは。株式会社エブリーの、デリッシュキッチンのiOSチームで1ヶ月の間インターンをしていました、鶴見です。

デリッシュキッチンは、「作りたい!が見つかる」をコンセプトにした、国内最大級のレシピ動画メディアです。 料理のレシピを動画で分かりやすく紹介していて、アプリではレシピの検索や、気に入ったレシピの保存(お気に入り)などの機能を提供しています。

インターンでは、WWDC26でアップデートされたApp IntentsやSiri AI関連の技術をプロダクトに組み込むことに取り組みました。 まずは、デリッシュキッチンのコア機能であるレシピ検索をSiri経由で利用できるようにすることをゴールに設定しました。具体的には、ユーザーがSiriに作りたい料理やレシピについて曖昧なリクエストを伝えるだけで、デリッシュキッチンのレシピが提案される体験を目指して検証を進めました。しかし、後述する技術的な制約により、当初想定していた体験を実現することはできませんでした。

代わりに、次の 2 つの入口を作りました。

  • Spotlight(iPhone の検索)から、レシピのタイトルでレシピを検索できる
  • Siri AI に「デリッシュキッチンで〇〇を検索して」と頼むと、アプリの検索結果画面が開く

本記事では、上記の実装について紹介をします。

なお、本記事の内容は次の環境で検証したものです。ベータ版で検証しているため、正式版では挙動が変わっている可能性があります。

  • iOS 27.2 beta 3
  • Xcode 27
  • Siri AI と端末の言語:英語(ベータ版では、日本語の設定で Siri AI を使えなかったため)

前提知識

App Intents は、アプリの機能やデータを Siri、Spotlight、ショートカットアプリなどに公開するためのフレームワークです。 アプリのデータ(レシピなど)は AppEntity、アプリの操作(レシピを検索するなど)は AppIntent として定義します。

iOS 27 では Siri が刷新されて Siri AI となり、自然な文章で頼みごとができるようになりました。 Siri AI がアプリのデータや操作を理解して使うには、Entity や Intent を App Schema に準拠させる(Apple が決めた型の定義に合わせる)必要があります。 App Schema は、メール・写真・カレンダー・メモといった用途(ドメイン)ごとに Apple が用意している型の定義です。 用意されているドメインの一覧は、Apple のドキュメント「アプリスキーマドメイン」で確認できます。

以降のコードに出てくる RecipeEntity は、デリッシュキッチンのレシピを Siri やショートカットアプリで使えるようにするために定義したものです。レシピのタイトルやサムネイル、材料名を連結したテキストデータなどを持っています。

何ができるかの見極め

新しい技術なので、まず「そもそも何ができるのか」を調べてから、「どう作ればいいのか」を調べるという順番で進めました。

機能調査:そもそも何ができるのか

最初は、新しい Siri AI で何ができるようになるのかが分かりませんでした。そこで次の順番で調べました。

  1. WWDC26(Apple が毎年開催している開発者向けのカンファレンス)の発表を見て、イメージを掴む
  2. Apple のデモアプリを入れて、実際に Siri AI に話しかけてみる

「はじめに」で書いたとおり、Siri AI と端末の言語は英語に設定して試しています。 ただ、言語を英語に設定したままでも、日本語で話しかければ応答は返ってきました。

実装調査:どう作ればいいのか

何ができるのかのイメージを掴んでから、作り方を調べました。

  1. デモアプリの解説ページを読み、実装を理解する
  2. Siri AI 対応に必要な実装の公式ドキュメントを読む

ベータ版での壁

調査と実装の途中では、次のような壁がありました。

  • 最新技術なので資料が少なく、何ができて何ができないのかが分からない
  • 動作確認は iOS のベータ版で行うため、うまく動かないときに、原因が自分の実装なのか OS なのかの判断が難しい

動かして確かめるだけでは、原因を切り分けきれませんでした。 そこで、App Schema のドキュメントなどを読み込み、「この仕様なら、こういう要件は実現できるはずだ」というイメージを先に固めるようにしました。 できる・できないの判断は、実際の挙動よりも、ドキュメントに書かれた仕様からの推論を中心にしました。

App Schema の壁と落とし所

当初の目標は、「Siri AI に話しかけるだけで、アプリ名を言わなくてもデリッシュキッチンのレシピが表示される」ことでした。 しかし調査を進めるうちに、この目標は実現できないことが分かりました。

Siri AI がレシピを認識するには、RecipeEntity を App Schema に準拠させる必要があります。 ところが、App Schema のドメインは Apple が用意したものに限られていて、「レシピ」に当てはまるものがありませんでした。

そこで、今の App Schema でも実現できる範囲に絞り、次の 2 つを実装することにしました。

入口 使う仕組み できること
Spotlight IndexedEntity アプリを開かなくても、レシピのタイトルで検索した結果にレシピが表示される
Siri AI .system.searchInApp スキーマ キーワード(料理名)付きでアプリの検索結果画面を開く

searchInApp は「システムとアプリ内検索」ドメイン(コード上は .system)に含まれる、「アプリの中で検索する」ためのスキーマです。 扱うデータの種類を問わないので、レシピのドメインがなくても、これなら Siri AI からアプリを呼び出せます。

実装①:IndexedEntity で Spotlight に索引登録

IndexedEntity は、Siri AI が登場する前の iOS 18 から使える仕組みで、アプリのデータを Spotlight で検索できるようにするためのものです。 Siri AI 向けの新しい API ではありませんが、これを使って Spotlight からレシピへの入口を作りました。

次の画像は、Spotlight で「基本のプ」と入力したときの様子です。索引に載せたデリッシュキッチンのレシピ「基本のプリン」が、検索結果に表示されています。 なお、本記事の画像はすべて開発用のビルドで撮影しているため、アプリ名が「開発」と表示されています。

ただし、検証では、入力が 3 文字以下のときは、索引に載せたレシピが検索結果に表示されませんでした。画像のように 4 文字入力すると表示されます。 Apple Developer Forums にも、iOS 17 以降、アプリが索引に載せた内容は 4 文字以上入力しないと Spotlight に表示されない、という同様の報告があります。ただ、2026 年 10 月時点で Apple からの回答はなく、仕様なのか不具合なのかは分かっていません。

RecipeEntity を IndexedEntity に準拠させる

IndexedEntity に準拠させると、Spotlight の索引(検索に使うためのデータ)に Entity をそのまま登録できるようになります。 索引への登録や削除は、CSSearchableIndex というクラスを通して行います。

RecipeEntity に summary(リード文と説明文)と keywords(カテゴリとタグ名)のプロパティを足し、材料と合わせて索引に載せています。

@available(iOS 18.0, *)
extension RecipeEntity: IndexedEntity {
    var attributeSet: CSSearchableItemAttributeSet {
        let attributeSet = defaultAttributeSet
        attributeSet.contentDescription = [summary, ingredientsText]
            .filter { !$0.isEmpty }
            .joined(separator: "\n")
        attributeSet.keywords = keywords
        return attributeSet
    }
}

そのため、RecipeEntity 自体は iOS 17 でも使えるようにしたまま、IndexedEntity への準拠だけを extension で iOS 18 以降に足しています。 また、@Property(indexingKey:)(プロパティごとに索引の項目を指定する書き方)は iOS 18.4 以降の API です。プロパティは iOS 17 でも使う RecipeEntity の本体で宣言しているため、これを付けることができません。代わりに、索引に載せる値は attributeSet で渡しています。

索引に載せるレシピを絞る

索引への書き込みは、RecipeIndexer というクラスにまとめています。登録・削除のタイミングは次のとおりです。

タイミング 処理
起動時・ログイン時 索引を全件消して、お気に入りと閲覧履歴から入れ直す
レシピを閲覧したとき そのレシピを索引に追加する
お気に入りに追加したとき そのレシピを索引に追加する
お気に入りから外したとき 閲覧履歴にもなければ、索引から削除する

書き込みを 1 本の列に並べる

お気に入りに追加したときは、API でレシピの詳細を取得してから索引に書き込むため、少し時間がかかります。 このとき、呼び出しごとに別々に書き込むと、お気に入りを付けてすぐ外したときに「外す」処理が先に終わり、あとから「追加」が書き込まれて、外したはずのレシピが索引に残ってしまいます。 そこで、索引への書き込みの依頼はすべて AsyncStream(非同期に値を順番に流すための仕組み)に並べ、1 つのタスクが届いた順に 1 件ずつ処理するようにしました。

次のコードは、説明のために簡略化したものです。

@available(iOS 18.0, *)
@MainActor
final class RecipeIndexer {
    static let shared = RecipeIndexer()

    /// 索引への書き込みの依頼
    private enum Event {
        /// 索引を全件入れ替える
        case rebuild
        /// 閲覧したレシピを載せる
        case index([RecipeEntity])
        /// お気に入りに追加したレシピを載せる
        case add(RecipeEntity.ID)
        /// お気に入りから外したレシピを消す
        case removeFavorite(RecipeEntity.ID)
    }

    private let index = CSSearchableIndex(name: "delish_recipes")

    private let eventContinuation: AsyncStream<Event>.Continuation

    private init() {
        let (events, eventContinuation) = AsyncStream.makeStream(of: Event.self)
        self.eventContinuation = eventContinuation

        // 1 つのタスクが、依頼を届いた順に 1 件ずつ処理する
        Task {
            for await event in events {
                await handle(event)
            }
        }
    }

    /// 起動時・ログイン時に呼ぶ
    func rebuild() {
        eventContinuation.yield(.rebuild)
    }

    /// レシピを閲覧したときに呼ぶ
    func addWatched(_ recipe: Recipe) {
        eventContinuation.yield(.index(RecipeEntity.entities(for: [recipe])))
    }

    // ...
}

アプリの各所からは rebuild() や addWatched(_:) を呼ぶだけで、索引への実際の書き込みは列を処理するタスクだけが行います。 お気に入りの追加・削除も、同じように Event として列に並べています。

起動時に索引を入れ替える

閲覧履歴から押し出された古いレシピや、ログインし直す前のアカウントのレシピなど、列を通らずに対象から外れたレシピが索引に残り続けないよう、起動時とログイン時には索引を全件入れ替えています。 次の rebuildIndex() は、列から .rebuild が届いたときに呼ばれる処理です。

private func rebuildIndex() async {
    // お気に入りと閲覧履歴のレシピを並行して取得する
    async let watched = Self.fetchWatched()
    async let favorites = Self.fetchFavorites()
    // オフラインなどで片方でも取れなかったときは、今の索引を消さずに残す。次の起動・ログインでやり直す
    guard let watchedEntities = await watched,
          let favoriteEntities = await favorites else {
        return
    }

    // 両方に入っているレシピを 1 つにまとめる
    var entities: [RecipeEntity.ID: RecipeEntity] = [:]
    for entity in favoriteEntities + watchedEntities {
        entities[entity.id] = entity
    }

    // 索引の失敗はアプリの操作に影響させない
    try? await index.deleteAllSearchableItems()
    try? await index.indexAppEntities(Array(entities.values))
}

ポイントは次の 3 つです。

  • お気に入りと閲覧履歴のレシピを async let で並行して取得する
  • どちらかの取得に失敗したときは、今の索引を消さずに残す(オフラインで起動したときに索引が空になるのを防ぐ)
  • 両方に入っているレシピは、ID をキーにした辞書で 1 つにまとめてから索引に載せる

実装②:searchInApp で Siri AI からアプリに遷移

searchInApp スキーマに準拠した Intent

Siri AI からの呼び出しには、WWDC26 で新しく発表された App Schema の 1 つである searchInApp を使いました。 Intent に @AppIntent(schema: .system.searchInApp) を付けると、呼び出しのフレーズ(Siri に話しかける決まった言い回し)を AppShortcutsProvider に登録しなくても、「デリッシュキッチンで〇〇を検索して」のような自然な文章から Intent が呼ばれます。 受け取ったキーワードを使って、アプリの検索結果画面へディープリンク(URL でアプリ内の特定の画面を開く仕組み)で遷移させています(参考:System and in-app search)。

次の GIF は、Siri AI に「開発でカレーを検索して」と頼み、アプリの「カレー」の検索結果画面が開くまでの様子です。 前述のとおり開発用のビルドのため、「デリッシュキッチンで」の代わりに「開発で」と頼んでいます。

@available(iOS 27.0, *)
@AppIntent(schema: .system.searchInApp)
struct SearchRecipeBySiriAI {
    static let searchScopes: [StringSearchScope] = [.general]

    var criteria: StringSearchCriteria

    @MainActor
    func perform() async throws -> some IntentResult {
        let keyword = criteria.term.trimmingCharacters(in: .whitespacesAndNewlines)

        // お気に入りや閲覧履歴の一覧を指す語なら、検索せずにその画面を開く
        if let screen = MyRecipeSchemeType(searchTerm: keyword) {
            screen.openInApp()
            return .result()
        }

        var allowed = CharacterSet.urlPathAllowed
        allowed.remove("/")
        guard !keyword.isEmpty,
              let encoded = keyword.addingPercentEncoding(withAllowedCharacters: allowed),
              let url = URL(string: "\(SchemeType.search.urlString)/\(encoded)") else {
            return .result()
        }

        // アプリが起動していない状態から開いたときは、起動画面が終わるまで遷移を待つため、ディープリンクの遷移キューに載せる
        PopupMediator.shared.handleLink(url: url, scheme: SchemeType.search.rawValue)
        return .result()
    }
}

ポイントは次の 3 つです。

  • criteria.term に、Siri AI が聞き取った検索キーワードが入る(searchScopes と criteria は、スキーマで決められているプロパティ)
  • アプリ側は URL のパスの 1 つ目の区切りだけを検索語として読むため、「ご飯/パン」のような語に含まれる / もエンコードして、1 つの検索語にまとめる
  • PopupMediator と SchemeType は、ウィジェットや通知からの遷移でも使っている、アプリ既存のディープリンクの仕組み。これに載せることで、アプリが起動していない状態から開いたときも、起動画面が終わってから検索結果画面に遷移する

お気に入り・閲覧履歴画面への遷移

「デリッシュキッチンのお気に入り」のように頼んだときも、searchInApp には「お気に入り」という検索キーワードとして届きます。 そこで、キーワードが一覧画面そのものを指しているかを MyRecipeSchemeType で判定し、指していればその画面へ遷移させています。

次の GIF は、Siri AI に頼んでお気に入り画面と閲覧履歴画面を開いている様子です。

extension MyRecipeSchemeType {
    /// 一覧画面そのものを指す言い方。完全一致で判定する
    private var searchTerms: Set<String> {
        switch self {
        case .favorites:
            ["お気に入り", "お気に入りレシピ", "お気に入りのレシピ", /* ... */]
        case .histories:
            ["閲覧履歴", "履歴", "最近見たレシピ", /* ... */]
        }
    }

    /// Siri AI から渡された検索キーワードが一覧画面を指していれば、その画面を返す
    init?(searchTerm: String) {
        // 空白や、「画面」「一覧」のように画面を指す接尾辞を取り除いてから判定する
        let normalized = Self.normalize(searchTerm)
        guard let screen = Self.allCases.first(where: { $0.searchTerms.contains(normalized) }) else {
            return nil
        }
        self = screen
    }

    /// マイレシピのタブから、この一覧画面へ遷移する
    @MainActor
    func openInApp() {
        guard let url = URL(string: urlString) else {
            return
        }
        // 検索結果画面と同じく、ディープリンクの遷移キューに載せる
        PopupMediator.shared.handleLink(url: url, scheme: SchemeType.myrecipe.rawValue)
    }
}

まとめ

iOS 27 の Siri AI にレシピを直接表示させるという当初の目標は、App Schema にレシピのドメインがないため実現できませんでした。 それでも、Spotlight と Siri AI という、アプリの外からレシピへの入口を 2 つ作ることができました。

今回一番学んだのは、最新技術はまず「できること・できないこと」の見極めから始める ということです。 資料が少なく、ベータ版では不具合の原因が自分の実装なのか OS なのかも分かりにくいため、いきなり作り始めると、できないことに時間を使ってしまいます。 WWDC の発表やデモアプリで何ができるのかを先に確かめ、ドキュメントの仕様から実現できる範囲を見極めたことで、早い段階で落とし所を決められました。

資料の少ない最新技術を学び、実装まで落とし込むのは今回が初めての経験でした。iOS エンジニアを目指す自分にとって、良い予習になったと思います。

今後 App Schema にレシピに当てはまるドメインが追加されれば、Siri AI に直接レシピを表示させるという当初の目標にも再挑戦できるはずです。

最後まで読んでいただき、ありがとうございました。

本番DBからDatabricksへ「何を渡すか」を、マイグレーションと同じPRでレビューする

はじめに

こんにちは、トモニテ開発部の吉田です。

現在、トモニテではデータ基盤(Databricks)の整備に取り組んでいます。これまでの分析は個人が作成したスプレッドシートに頼る部分が多く、人やシートによって指標の定義が違ったり、誰が何を見られるのかを把握しにくかったりしたため、データを一元化することにしました。

その一環として、アプリの本番 DB のデータを Databricks に連携します。本番 DB には扱いに気をつけるべき情報が多く入っているので、開発部では「どのテーブル・カラムを Databricks に渡すか」をアプリのリポジトリで定義し、デプロイのたびにその定義を DB の権限と view に反映する仕組みをつくりました。

この記事は、本番 DB をデータ基盤につなごうとしていて、個人情報の扱いに悩んでいるエンジニアに向けて、その設計で考えたことを紹介します。伝えたいのは次の2点です。

  1. 連携の分類をマイグレーションの手順に組み込み、人が気づくことに頼らない
  2. 本番 DB を書き換えるツールは、失敗したら見える範囲を減らす側に倒す

全体の流れは次のとおりです。

図は本番環境の流れです。開発環境でも同じ流れで同期します。

連携に必要なこと

Databricks が本番 DB(Aurora MySQL 3.10.4、MySQL 8.0 互換)のデータを取り込むには、次の2つが必要です。

  • Databricks の環境から本番 DB のリードレプリカに届く接続経路
  • Databricks が参照に使う、読み取り専用の DB ユーザー

経路はインフラ側で用意すれば済みますが、もう1つの「読み取り用のユーザーに何を見せるか」は、そう簡単には決められません。この記事の本題はここです。

何をどこで絞るか

トモニテは妊娠・育児期の家族向けのアプリで、DB には扱いに気をつけるべき情報が多く入っています。一方で、分析に必要な情報もあり、テーブル・カラムの単位で「渡す/粗くして渡す/渡さない」を決める必要があります。

DB 側で絞る

絞り方には、次の2つがあります。

  1. データ基盤にはすべて取り込み、分析向けにはデータ基盤側でマスクする
  2. 読み取り用ユーザーの権限で、問題のないものだけを見せる

一度 Databricks に取り込まれたデータは、コピー先まで含めて消すのが難しくなります。データの発生元である DB 側で絞るのが一番漏れのない形なので、2を選びました。

カラム単位の GRANT ではなく view で渡す

最初は、GRANT SELECT (id, created_at, ...) ON users のように機密カラム以外のカラムだけに GRANT する方法(カラム単位の GRANT)を試しましたが、そのテーブルを Databricks から読めなくなりました。Databricks からは、Lakehouse Federation(外部の DB を Unity Catalog のカタログとして見せる機能)の MySQL 接続で読んでいます。

手元の MySQL 8.0 で、カラム単位の GRANT だけを持つユーザーをつくって確かめると、次のようになりました。

クエリ 結果
SHOW TABLES、information_schema.COLUMNS テーブルは見え、カラムは許可したものだけが見える
SELECT id, created_at FROM users(許可したカラムだけを指定) 読める
SELECT * FROM users WHERE 1=0 ERROR 1142 (42000): SELECT command denied to user ... for table 'users'

MySQL では、許可していないカラムを含む SELECT * は、行を1件も返さないクエリでも拒否されます。しかもエラーはカラムではなくテーブル単位の拒否(1142)として返るので、テーブルの権限そのものが無いように見えます。

一方、Spark の JDBC は、テーブルのカラムと型を調べるときに既定で SELECT * FROM <テーブル> WHERE 1=0 を送ります。この既定は JdbcDialect.getSchemaQuery で、MySQL 用の MySQLDialect はこれを上書きしていません。

github.com

github.com

Databricks も同じクエリを送っているのかを、Aurora の performance_schema で確かめました。events_statements_summary_by_digest は、実行されたクエリの値を ? に置き換えた形ごとに集計した表で、実行回数・返した行数・エラーの回数に加えて、置き換える前のクエリの例(QUERY_SAMPLE_TEXT)も持っています。users について、元のテーブルと、後述する機密カラムを除いた view(<masked> のデータベースに置いたもの)を、次のクエリで比べました。

SELECT QUERY_SAMPLE_TEXT, COUNT_STAR, SUM_ROWS_SENT, SUM_ERRORS
FROM performance_schema.events_statements_summary_by_digest
WHERE DIGEST_TEXT IN (
  'SELECT * FROM `<元のデータベース>` . `users` WHERE ? = ?',
  'SELECT * FROM `<masked>` . `users` WHERE ? = ?'
);
QUERY_SAMPLE_TEXT COUNT_STAR SUM_ROWS_SENT SUM_ERRORS
SELECT * FROM `<元のデータベース>`.`users` WHERE 1=0 41 0 7
SELECT * FROM `<masked>`.`users` WHERE 1=0 40 0 0

WHERE 1=0 を付けた SELECT * が届いていて、1行も返していませんでした。Lakehouse Federation も、Spark と同じ方法でカラムを調べていると考えられます。カラム単位の GRANT を試した元のテーブルにはこのクエリのエラーが記録されていて、view では 0 回でした。カラムを調べる段階で拒否され、テーブルごと読めなくなったと考えています。

許可したカラムを明示したクエリ(SELECT * FROM (SELECT id, created_at FROM users) t)なら通るので、読む側でテーブルごとにカラムを指定すれば回避はできます。ただ、それでは「何を渡すか」の定義が Databricks 側にも分散します。そこで、機密カラムを除いた view を別のデータベース(以下、masked)につくって渡すことにしました。view なら SELECT * で読んでも、出てくるのは view が出力するカラムだけです。連携が不要なテーブルには、権限を付けません。

加工も Databricks の ETL ではなく view で行います。ETL で加工すると、加工前の値が、取り込んだデータをそのまま置く層(Bronze)に残ってしまうためです。

view と Unity Catalog の二段構え

view で落とす・粗くするのが一段目、Databricks 側の Unity Catalog で見られる人を絞るのが二段目です。view で粗くしきれないものは、二段目で閲覧者を限定します。

分類の方針

どのカラムを渡すかは、厳しめにルールを整備しました。

  • 認証情報や、それ単独で個人情報になるものは渡さない
  • 単独では個人を特定できなくても、ほかの情報と容易に照合することで個人を識別できるもの(容易照合性)も考慮し、渡さないか、分析に必要な粒度まで粗くして渡す
  • 判断に迷ったら「渡さない」側に倒す

迷ったら渡さない側に倒したのは、あとから必要になれば view を直して追加できますが、一度渡したものを消すのは難しいからです。厳しめにした分、運用を始めてメンバーから「分析しづらい」という声が出れば、見直すつもりです。

連携するテーブル・カラムを tables.yml で宣言する

この方針では、テーブルの追加・変更のたびに権限を整理する必要があります。手作業で整理する運用は避けたいので、定義をリポジトリで管理し、CI で検査、デプロイで反映する仕組みにしました。

定義は、アプリ(API サーバー)のリポジトリに置いています。中心になるのは tables.yml で、全テーブルを次の3つに分類します。

  • grant:そのまま渡す
  • view:機密カラムを除いた view で渡す
  • exclude:渡さない

view のテーブルは、さらに全カラムを include(そのまま渡す)/transform(加工して渡す)/exclude(渡さない)に分け、transform には加工内容と理由を、exclude には理由を書きます。

現在は全 201 テーブルを分類していて、内訳は grant が 165、view が 30、exclude が 6 です。

# テーブル名・カラム名は説明用の例です
tables:
  table_a: {policy: grant}
  table_b:
    policy: view
    columns:
      include: [id, status, created_at]   # そのまま渡すカラム
      transform:                          # 加工して渡すカラム: 加工内容と理由
        column_x: 粒度を粗くする。元の値はほかの情報と照合すると個人を特定できる
      exclude:                            # 渡さないカラム: 理由
        column_y: 個人を特定できる情報
  table_c:
    policy: exclude
    reason: 連携が不要

この定義と、view の SQL(views/*.sql)、Databricks の読み取り用ユーザーへの GRANT(grants.sql)を1つのディレクトリで管理しています。

なぜインフラのリポジトリではなく、アプリのリポジトリに置いたか

トモニテのインフラは Terraform で別のリポジトリが管理していますが、定義はアプリのリポジトリに置きました。

  • 見直しのきっかけになるテーブル・カラムの追加はアプリのマイグレーションで行われるので、同じ PR で分類と view も更新・レビューできる
  • 分類漏れの検出にはマイグレーション済みの DB が必要で、アプリの CI ではすでに MySQL を立ててマイグレーションを流している

Databricks からの経路や DB ユーザー・IAM などは、引き続きインフラのリポジトリで管理しています。

分類を書くまで CI が通らないようにする

CI では、マイグレーション後のスキーマと定義を突き合わせ、次のものがあれば落とします。

  • 分類されていないテーブル、view のテーブルの分類されていないカラム
  • 元のテーブルの変更で壊れた view
  • exclude・transform にしたカラムを、そのまま出力している view
  • grants.sql と tables.yml の食い違い

これで、マイグレーションでテーブルやカラムを足すと、分類を書くまで CI が通らなくなります。「追加に人が気づく」ことに頼らず、分類を書くことがマイグレーションの手順に組み込まれる形です。

開発メンバーにとっては、マイグレーションのたびに分類を書く手間が増えます。この手間をどう感じるかは、これから運用しながら確かめていきます。

開発環境の DB でも実際に止まった

同じ検査は、後述の同期コマンドもデプロイのたびに実際の DB に対して行います。開発環境で動作確認したところ、定義に分類の無いカラムがある状態で、同期が想定どおり止まりました。別の機能の開発で開発環境の DB にはすでにカラムが追加されていましたが、連携定義にはそのカラムの分類がなかったためです。止まったのは定義の検証の段階(Apply の前)なので、DB には何も変えずに失敗が通知されました。

マイグレーションと定義のずれを、CI だけでなく実際の DB に対しても検知できることを確かめられました。

同期コマンド:差分(Plan)を計算して適用する

定義を DB に反映するのは、Go で書いた同期コマンドです。デプロイのたびに ECS のタスクとして起動し、定義を検証して排他をとったうえで、今の権限と view を読んで定義との差分(Plan)を計算し、適用します。適用後は状態を読み直して確かめ、変更か失敗があれば Slack に通知します。

宣言的で冪等に動くので、差分がなければ何もせず、通知もしません。定義に無い権限や view は外れます。手作業で付けた GRANT や、手でつくった view も、同期用ユーザーが外せる範囲で次の同期で外れます。

権限の管理には Terraform の MySQL provider などの既存ツールもありますが、定義をアプリのリポジトリに置いたので、同期コマンドもアプリのリポジトリに置き、アプリと同じ Go で書きました。

適用の順番を固定する

Plan は、必ず次の順番で適用します。

  • ① view の作成・更新
  • ② GRANT
  • ③ REVOKE と、定義に無い view の DROP

この順番には、次のルールを決めています。

  • ①が1本でも失敗したら、②は流さない。 新しい view ができていないのに、GRANT だけが増える状態を避けるためです
  • ①の中、②の中では、1本が失敗しても残りは止めない。 関係のない文まで巻き込んで止めないためです
  • ③は①②の結果にかかわらず必ず全部流し、1本が失敗しても残りを続ける。 見える範囲を減らす操作は、止める理由がないためです

適用後に確かめ、だめなら段階的に安全側へ倒す

適用が終わったら、状態(権限と view の一覧)と、masked の各 view の出力カラムを読み直します。そのうえで、機密カラム(exclude・transform にした元のカラム)を出している view があれば、次のように段階的に対応します。

  1. その view を DROP する。取り込みは止まるが、漏れは止まる
  2. DROP できなければ(ほかのユーザーが作った view など)、masked 全体の SELECT を REVOKE する。全 view の取り込みが止まるが、機密カラムが見え続けるよりは安全
  3. それもできなければ、機密カラムが見え続けていることを至急の通知で知らせる

同期コマンド自体を信用しすぎない

同期は本番 DB の権限と view を書き換えるので、誤って別のユーザーや別のデータベースを触らないよう、コマンド自体にも制限をかけています。

発行できる SQL を4種類に固定する

  • masked の view をつくる・更新する CREATE OR REPLACE VIEW
  • 読み取り用ユーザーに権限を付ける GRANT SELECT
  • 読み取り用ユーザーの権限を外す REVOKE
  • masked の view を消す DROP VIEW

制限は二段構えです。

  • 生成時:SQL は専用の型(Statement)のコンストラクタからしか作れず、この4種類以外を組み立てる手段がない
  • 実行直前:実行する側が、許可リスト(正規表現)で SQL の文字列を再検査し、一致しないものは実行しない

同期用ユーザーの権限を絞る

同期用の DB ユーザーには、必要な権限だけを付けています。同期で外せる権限も、同期用ユーザーが GRANT OPTION 付きで持っている範囲に限り、それ以外の権限が付いていた場合は、同期では直せないものとして毎回失敗で通知します。

この最小権限で同期が通ること、2回目の同期では SQL を1本も送らないこと(冪等)、手作業で足した権限が次の同期で外れることは、CI の MySQL で本物の定義を使った結合テストで確かめています。

デプロイとの連動

同期は、開発環境・本番へのデプロイの後に、別のジョブとして起動します。定義やマイグレーションなど同期に関係するものが変わったときだけ動き、変わったかを判定できないときは、見落とさないよう同期する側に倒しています。失敗した実行は成功に数えないので、その変更は次のデプロイで同期し直されます。

割り切ったこと

最後に、この仕組みでは検出できないことも書いておきます。

  • view の検査は、exclude・transform にした元のカラム名がそのまま出力に無いかだけを見ている。別名を付ける、式で包むといった書き方で機密カラムを出しても検出しないので、view の SQL の変更は PR のレビューで確かめる
  • grant のテーブルに機密カラムが足された場合は、CI では検出できない。マイグレーションのレビューで view に切り替える
  • 読み取り用ユーザーのグローバル権限やロール経由の権限は、同期用ユーザーが読めないので検出できない

すべてを機械で防げるわけではないので、機械で防げる範囲と、レビューで確かめる範囲を README に明記しています。

まとめ

本番 DB のデータを Databricks に安全に渡すために、「どのテーブル・カラムを渡すか」をアプリのリポジトリで宣言し、デプロイのたびに DB に反映する仕組みをつくりました。冒頭の2点をあらためて挙げます。

  1. 連携の分類をマイグレーションの手順に組み込み、人が気づくことに頼らない。 分類を書くまで CI が通らず、分類はマイグレーションと同じ PR でレビューする
  2. 本番 DB を書き換えるツールは、失敗したら見える範囲を減らす側に倒す。 適用の順番を固定し、機密カラムが見えていれば view の DROP、masked 全体の REVOKE と段階的に安全側へ倒す

データ基盤に何を渡すかを、シートの共有範囲ではなく、リポジトリの定義で管理できるようになりました。これからは、一元化したデータの上で分析を進めていきます。

RAGとJevで「ベクトルDBに根拠となる答えがない」ことを見分ける仕組みを作った話

RAGとJevで「ベクトルDBに根拠となる答えがない」ことを見分ける仕組みを作った話

はじめに

こんにちは。1か月間のインターンで、サーバーサイド(Go)を担当した橋本です。

インターンでは、AIエージェントの機能追加の設計・実装に携わりました。この記事では、その中でもRAG(Retrieval-Augmented Generation)の検索の部分に焦点を当てます。RAGは、質問に関係する文書を探してLLMに渡し、その文書をもとに回答を作成する仕組みです。ここではデリッシュキッチンの情報を検索し、AIの回答の根拠として使えるかどうかを検討しました。

作ってみて一番難しかったのは、「ベクトルDBに根拠となる答えがないことをどのように見分けるか」でした。関係の薄い情報をLLMに渡してしまうと、LLMはそれをもとにもっともらしいが正確ではない回答を生成してしまう可能性があります。よってベクトルDBに根拠となる情報が無い場合は、LLMに回答させないようにする必要があります。

この記事では、次の2つのトピックに絞ります。

  • HYBRIDとANNという2つの検索を組み合わせて、候補を絞る仕組み
  • 絞った候補が質問に答えているかを、TypeSafeのAIモデルJevで文書ごとに判定する仕組み

HYBRIDとANNはベクトルDBに対する検索方式で、具体的なアルゴリズムは後述します。

最後に、これらの手法についてローカルで計測した結果も記述しています。なお、以下に出てくる質問や文書の例は、説明のために作ったものです。

全体の流れ

前提として、ベクトルDBとインデックスはDatabricksのAI Searchというサービスにてホストされており、バックエンドサーバーからベクトルDBに対して直接リクエストするような形式を取っています。

またインデックスは、文書を段落レベルの単位(チャンク)に分けた上で埋め込みベクトルを生成しています。

処理の全体像は以下の通りです。

検索方式を決めるまで

インターンで一番やりがいを感じたのは、この検索方式を決めるところでした。自分の考えを特に多く入れられた部分でもあるので、どう考えて今の形に落ち着いたのかを書きたいと思います。検索方式は何度か変わり、HYBRIDから始めてANNに移り、最後に両方を組み合わせる形になりました。

欲しかった候補

例えば「ハンバーグの焼き時間は?」と聞かれたとします。候補に来てほしいのは、「ハンバーグの作り方」のようなハンバーグについての文書です。「鶏むね肉のソテーの焼き時間」のような、別の料理の焼き時間の文書ではありません。

ベクトルの近さだけで探すと、別の料理の文書でも質問と同じく「焼き時間」について書かれていれば上位に来るおそれがありました。そこで最初は、HYBRIDを使うことを考えました。HYBRIDはベクトルの近さとキーワードの一致を合わせて並べるので、「ハンバーグ」という言葉が入った文書が上位に来やすく、聞かれている対象を外しにくくなります。

HYBRID単体では根拠となる回答があるかを判断できない

HYBRIDを使う場合、scoreが閾値より低ければ「答えが無い」と判定するつもりでした。ところが、設計を詰める中で、HYBRIDではこの判定が難しいことに気づきました。

HYBRIDは、ベクトル検索とキーワード検索の結果を、Reciprocal Rank Fusion(RRF)で1つにまとめる検索です。DatabricksのAI Searchでは、チャンクxについて次の値を計算します(rankは、それぞれの検索でのxの順位で、1位を1と数えます。60はRRFの定数kで、AI Searchでは60です)。

AI Searchが返すscoreは、この値を取りうる最大値で割り、最大が1になるようにしたものです。一定の値で割るだけなので、scoreが順位で決まることは変わりません。

このように、HYBRIDのscoreは2つの検索の順位から計算するので、検索語とチャンクがどれだけ近いかの目安にはなりません。インデックスの文書がどれも質問と関係なくても、上位の文書には、順位に応じた高いscoreが付きます。そのためscoreを見ても、答えのある文書があるのか、関係のない文書しか無いのかを区別できません。

ANNと、見出しを足した埋め込み

次に、ANN(ベクトルの近さだけで探す検索)に切り替えました。AI SearchのANNは、検索語のベクトルqとチャンクのベクトルxの距離(ユークリッド距離)から、次の式でscoreを計算します。

‖q − x‖ はqとxのユークリッド距離です。距離が0ならscoreは1になり、遠いほど小さくなります。使っているOpenAIの埋め込みは長さ1に正規化されているので、距離は最大でも2になり、実際のscoreは0.2〜1の間に収まります。

HYBRIDでは、どの文書も関係なくても上位に高いscoreが付きますが、ANNでは、どのチャンクも遠ければscoreも低いままです。ANNのscoreは検索語とチャンクの近さそのものなので、閾値を付けられます。残った心配は、聞かれている対象を外すことです。この点をインデックスの側で補うために、埋め込む文を工夫しました。

RAGでは、文書を段落のような小さな単位(チャンク)に分け、チャンクごとにベクトルにするのが一般的です。文書全体を1つのベクトルにすると、そのベクトルはいろいろな関心事を含み、細かい質問に対応しくくなってしまいます。

ただ、チャンクに分けると、今度は文脈が抜け落ちます。文書の中ではタイトルや見出しが何について書かれているかを示していますが、段落だけを切り出すと、その手がかりが無くなります。例えば、次の段落があるとします。

中火で 5 分ほど焼き、裏返してふたをします。

この段落だけでは、何を焼くのかが分かりません。同じ文書のタイトルが「ハンバーグの基本の作り方」で、段落が「焼き方」という見出しの下にあれば、「ハンバーグは中火で5分ほど焼く」という内容だと分かります。もし段落だけをベクトルにすると、「ハンバーグ」や「焼き方」で聞かれてもこの段落はヒットしないでしょう。

そこで、埋め込む文には、チャンクの本文の前に、文書のタイトルと、そのチャンクが属する見出しをつなげて入れました。

文書のタイトル / 見出し / チャンクの本文

見出しが何階層かある文書では、チャンクのすぐ上にある見出しだけでなく、それより上の階層の見出しまでつなげます。すぐ上の見出しだけでは、上の階層が示す文脈(「作り方」なのか「アレンジ」なのか)が抜け落ちるからです。

HYBRIDとANNの並行

ただ、見出しを足しても、ANNが見ているのはあくまでベクトルの近さです。固有の料理名や略語のように、言葉がそのまま一致するかどうかが決め手になる質問では、近さだけだと、似た話題の別の文書が上位に来るおそれが残りました。一方で、「答えが無い」を見分けるための閾値には、近さそのものを表すANNのscoreが要ります。

そこで、自分が出した案をもとにチームで相談して、2つを組み合わせる形に決めました。並べ替えはキーワードの一致も使えるHYBRIDに、明らかに遠い候補を閾値で落とすのは近さそのものをscoreで返すANNに任せます。インデックスに入れる見出しの工夫は、そのまま残しています。

具体的には、2つを並行に問い合わせ、HYBRIDの結果のうち、ANNの閾値を通ったチャンクを持つ文書のものだけを残します。次のコードは、説明のために簡略化したものです。

// HYBRID と ANN(閾値つき)を並行に問い合わせる。片方が失敗したら、もう片方も止める
var annHits, hybridHits []*Hit
g, gctx := errgroup.WithContext(ctx)
g.Go(func() (err error) { annHits, err = index.Query(gctx, annQuery); return })
g.Go(func() (err error) { hybridHits, err = index.Query(gctx, hybridQuery); return })
if err := g.Wait(); err != nil {
    return nil, err
}

// annQuery に閾値を付けてあるので、annHits には閾値を通ったチャンクだけが入っている。
// そのチャンクを持つ文書を「近い」とみなす
near := map[int64]struct{}{}
for _, h := range annHits {
    near[h.DocID] = struct{}{}
}
// HYBRID の結果は、近い文書のものだけを残す(並び順は HYBRID のまま)
hits := make([]*Hit, 0, len(hybridHits))
for _, h := range hybridHits {
    if _, ok := near[h.DocID]; ok {
        hits = append(hits, h)
    }
}

文書の単位で照らし合わせているのは、ANNとHYBRIDでは、同じ文書でも別のチャンクが返ってくることがあるからです。

自分で作ったベクトルを入れるインデックスでもHYBRIDを使えるかは、Databricksのドキュメントからは分からなかったので、ローカルで試して動くことを確かめました。ただ、少数の質問でANNだけの場合と比べたところ、最終の結果にはほとんど差が出ませんでした(後の「ローカルで試した結果」で詳しく記述しています)。HYBRIDを足した効果はまだ言い切れないので、設定でANNだけの形にも切り替えられるようにしました。

文書ごとのまとめ

インデックスから返ってくるのはチャンクの単位です。そこで、同じ文書から来たチャンクを1つの候補に束ね、文書のscoreは、その文書のチャンクの(HYBRIDの)scoreの最大値にします。このscoreは候補を並べる順番にだけ使い、上位10文書を判定にかけます。判定を通った文書からも、この順番のまま上位3文書を選びます。

同じ話題だが答えていない文書

ここまでで、明らかに意味が異なる候補は落とすことができます。 ただ、同じ話題だが質問の回答にはならない文書を完全に落とすことはまだできていません。

例えば「ハンバーグの焼き時間は?」と聞かれ、インデックスには「ハンバーグの由来」を紹介する文書しかないとします。この文書は焼き時間には答えていませんが、ハンバーグについて書かれているので、チャンクのベクトルは検索語のベクトルに近くなります。ANNの閾値を厳しくすれば落とせるかもしれませんが、そうすると今度は、答えている文書まで落ちてしまいます。

考えた案は次の3つでした。

案 結論 理由
ANNの閾値を厳しくする 見送り 答えている文書まで落ちる。閾値だけでは、同じ話題だが答えていない文書を分けられない
質問と文書の主題が一致するかを見る 見送り 主題が一致していても、聞かれたこと(焼き時間)が書かれているとは限らない
文書ごとにAIモデルで判定する 採用 この文書はこの質問に答えているかを、直接聞ける

最終的にチームで決めたのは、ANNの閾値で明らかに遠いものを落とし、残った上位10文書をAIモデルで判定する形です。

従来のLLMでは推論速度に少なからず影響が出るのが懸念だったのですが、Jevを使用すれば比較的影響を少なく実装できると思い、今回試してみることになりました。

Jevで文書ごとに判定する

Jevとnoul型

判定にはTypeSafeのJevを使いました。Jevは従来のLLMのようなテキスト生成をするのではなく、高速かつ型安全なデータ構造を出力することに特化した新しいAIモデルです。今回はCloudflareのWorkers AIのAPIから呼びだしています。

Jevに渡す問い(questions)の型にはいくつかあり、今回はnoulを選択しました。noulは、trueとfalseの基準を渡すと、trueに当たる確率を0〜1の数で返します。答えているかどうかを確率で受け取れるので、判定の閾値を後から調整できます。

判定に渡すもの

1文書ごとに、次の形でリクエストを送ります(文言は簡略化し、一般的な言い方に直しています)。

{
  "model": "typesafe/jev",
  "input": {
    "state": "質問: ハンバーグの焼き時間は?\nタイトル: ……\n\n[大見出し / 中見出し]\n本文の段落……\n\n[大見出し / 中見出し]\n本文の段落……",
    "questions": {
      "answers_question": {
        "type": "noul",
        "instructions": "You decide whether the blocks in the state answer the user's question. ... Use the headings only to understand where each block sits; do not count a heading alone as an answer.",
        "criteria": {
          "true": "The text of the blocks alone answers the question, at least in part.",
          "false": "The blocks are about the same topic but do not answer the specific thing that was asked, or they are about something else."
        }
      }
    }
  }
}

stateに判定の材料(質問と、見出し付きのチャンク)を、questionsに何を判定させるかを入れます。

工夫したのは次の4点です。

  • 渡すのは、その文書のチャンクのうち、検索のscoreが高い上位3つだけです。文書全体を渡すと長くなり、判定も遅くなるからです。答えが書かれた段落は質問と内容が近いので、上位3つに入っているはずだと考えました
  • チャンクには見出しも付けて渡しますが、見出しはその段落が文書のどこにあるかを示す手がかりとしてだけ使うよう、指示に書きました。例えば見出しに「焼き時間」とあっても、本文に焼き時間が書かれていなければ、答えているとは数えません
  • falseの基準には、「同じ話題だが、聞かれたことには答えていない」場合をはっきり書きました。ANNの閾値(ベクトルの近さ)で落とせずに残るのは、まさにこういう文書だからです
  • 広い質問は別に扱います。「ハンバーグについて教えて」のような質問なら、ハンバーグを説明している文書は答えていると数える、と指示に書きました。これが無いと、広い質問では「具体的なことに答えていない」として落ちかねません

返ってきた確率が判定の閾値(今は仮で0.5)以上なら、答えているとします。

ローカルで試すと、同じ文書でもANNとHYBRIDでは当たるチャンクが違い、判定に渡す3チャンクが変わる文書が58件ありました。それらの文書で、ANNだけのときとHYBRID+ANNのときのJevの確率の差は、中央値で0.01でした。渡すチャンクが多少変わっても、判定はほとんど変わらないようです。ただし、差が最大で0.61開いたものもあり、0.5をまたいで、通るかどうかが逆になったものが2件ありました。

並行判定とやり直し

10文書は並行して判定します。1文書ずつ順番に呼ぶと、待ち時間が文書の数だけ積み重なるからです。どれか1つの判定でエラーが起きても、その文書を判定できなかったものとして扱うだけで、ほかの文書の判定はそのまま続けます。前処理のHYBRIDとANNの問い合わせでは、片方が失敗したら両方を止めるerrgroupを使いましたが、ここでは1つの失敗でほかを止めたくないので、sync.WaitGroupを使っています。

// 1 文書の判定結果。判定できなかったときは Err に入れ、他の文書は止めない
type Verdict struct {
    Probability float64 // 「答えている」の確率
    Err         error
}

// 文書ごとの失敗は Verdict.Err で返すので、ここでは常に nil を返す
func (j *JevJudge) Judge(ctx context.Context, query string, docs []*Candidate) ([]*Verdict, error) {
    verdicts := make([]*Verdict, len(docs))
    var wg sync.WaitGroup
    for i, d := range docs {
        wg.Go(func() { // Go 1.25 の sync.WaitGroup.Go
            p, err := j.judgeOne(ctx, query, d)
            verdicts[i] = &Verdict{Probability: p, Err: err}
        })
    }
    wg.Wait()
    return verdicts, nil
}

Jevの判定1回にかかる時間は中央値で247 msでした。並行にしたので、判定の段階は数百msで終わっています。

判定でエラーが起きた文書は、最後に選ぶ3文書がまだそろわず、時間も残っているときに限り、1回だけ判定をやり直します。一方、答えていないと判定された文書はやり直しません。エラーと違って、判定そのものはできているからです。

判定の結果から、返すものは次の3通りに決まります。

判定の結果 返すもの
答えている文書が1つ以上ある その文書(上位3つまで)
すべての文書が「答えていない」と判定された 「答えが無い」
答えている文書が無く、判定できなかった文書が残った エラー

3つ目を「答えが無い」にしないのは、判定できなかった文書に答えが書かれているかもしれないからです。その場合に「答えが無い」と返すと、実際には答えがあるのに無いと伝えてしまいます。

閾値の決め方と、ローカルで試した結果

ANNの閾値と判定の閾値は、今は仮の値です。どちらの値にも同じトレードオフがあります。厳しくすると、答えが無い質問では正しく0件にできる代わりに、答えがある質問では正しい文書まで落としてしまいます。

そのため、評価では次の2つを分けて測ります。

指標 測るもの
検索の正しさ 正解の文書が上位3文書に入るか
答えが無い質問 答えが無い質問で、正しく0件になるか

RAGの評価では、LLMが渡された文書のとおりに答えを書けているかを測ることがよくあります。ただ、これだけでは検索の失敗が見えません。

例えば「ハンバーグの焼き時間は?」に対して、検索が鶏むね肉のソテーの文書を渡してしまったとします。LLMがその文書のとおりに「片面3分ずつです」と答えれば、文書に忠実なので、この測り方では満点になります。しかし、ユーザーが聞いたのはハンバーグの焼き時間なので、答えとしては間違いです。そのため、検索が正しい文書を選べているか(上の表の「検索の正しさ」)は、別に測る必要があります。

評価に使う質問には、答えが文書に書かれている質問、どの文書にも答えが無い質問、答えが一部にしか書かれていない質問の3種類を混ぜます。なお、評価のために外部のサービスであるJevへ送るのは、ユーザーが実際に送った質問ではなく、評価用に作った質問だけです。

ローカルで試した結果

評価用に作った15問、Jev判定なしと判定ありの差を比べました。Jevで判定すると、答えが無い質問の多くで、正しく「答えが無い」と返せるようになりました。その代わり、答えがある質問12問のうち1〜2問では、文書を全部落としてしまいました。

答えが無い質問に文書を返してしまった(5問中) 答えがある質問で文書を全部落とした(12問中)
判定なし 5 0
Jevで判定(ANNだけ) 1 1
Jevで判定(HYBRID+ANN) 1 2

どちらの列も、数が少ないほど良い結果です。

今回はどの組み合わせでもANNの閾値を0にしていたので、閾値では何も落ちません。そのため判定なしの場合は、どんな質問にも上位3文書がそのまま返り、答えがある質問では12問すべてで文書が残りました。一方で、「明日の東京の天気は?」「スマホの電池を長持ちさせる方法は?」のような、インデックスのどの文書とも関係のない質問にも文書を返してしまいました。

Jevで判定すると、答えが無い質問5問のうち4問で、正しく「答えが無い」と返せました。一方、答えがある質問でも、文書が1つも残らないものが、ANNだけで1問、HYBRID+ANNで2問ありました。そのうちの1つは、「薄力粉と強力粉の違いは?」のような、2つのものの違いを聞く質問です。インデックスには薄力粉の文書と強力粉の文書が別々にあり、どちらも1つだけでは違いに答えていないので、両方とも落ちました。文書を1つずつ判定する作りの弱みで、複数の文書にまたがる質問には別の扱いが要ります。

ANNだけとHYBRID+ANNの差は、今回はほとんど出ませんでした。判定にかける上位10文書は、一部が入れ替わっているだけでした。それでも、最終の結果が違ったのは1問だけで、それも判定に渡したチャンクの違いによるものでした。

推論速度の中央値は次のとおりです。

段階 時間(中央値)
検索語の埋め込み 145 ms
検索(ANNだけ) 213 ms
検索(HYBRID+ANN) 242 ms

HYBRID+ANNは2本を並行に問い合わせるので、ANNだけとの差は30 msほどです。判定の段階は、前に書いたとおり数百msです。

この結果には、次の注意点があります。

  • 質問は評価用に作ったもので、実際のユーザーの質問ではありません
  • 閾値は仮の値です(判定は0.5、ANNは0)。ANNの閾値で遠い候補を落とす効果は、まだ測れていません

学んだこと

  • HYBRIDのscoreは「近さ」ではない。 順位から作った値は並べ替えには使えても、答えの有無を閾値で見分けるのには使えません。scoreが何から計算されているかを確かめてから使う必要がある。
  • ベクトルの近さで分かるのは「意味が近いか」まで。 「聞かれたことに答えているか」は、近さとは別の問い。
  • 判定の結果は確率で受け取る。 はい/いいえで受け取ると、閾値を動かせません。Jevのnoulのように確率で返すものを使えば、評価を見ながら調整できます
  • 文書ごとの判定は、複数の文書にまたがる質問に弱い。 「AとBの違い」のような質問は、1つの文書だけでは答えられないので、文書が全部落ちることがあります

おわりに

RAGの「根拠となる答えが無い」ことをどう見分けるかは、作る前に思っていたよりずっと奥が深い問題でした。

1か月のインターンで、検索方式の選び方から判定の仕組みまで自分で案を考えて提案し、チームと相談しながら形にできました。評価では、判定を足すと、答えが無い質問の多くを排除できる傾向も見えました。

一方で、答えがある質問でも、文書を全部落とす場合があることや、複数の文書にまたがる質問に弱いことも分かりました。さらに質問を増やした評価は、これからの課題です。

お忙しい中、レビューをしてくださり、相談にも乗ってくださった 配属先のチームの皆さん、特に岩崎さん、ありがとうございました。