Token Lab検索

最初の実装:ローカル根拠検索アシスタント

最初の根拠検索アシスタントを作る:完全なローカル実装

小さな文書集合から、出典を追跡できる決定的な応答システムを作ります。契約、検索、回答保留を理解し、言語モデルやエージェントを加える前の基準を確立します。

出典とバージョン
この記事の目次

1. 問題と成果

当番エンジニアが手順書で “timeout retry” を検索するとします。対話エージェントの前に、公開文書とIDを返し、字句根拠がなければ保留する仕組みを作ります。返すのは原文です。LLM、意味検索、本番向け安全サービスではなく、将来のAIアプリの検索基準です。

Python実装と独立テストを作り、応答形式、順位計算、既知の失敗、推論の追加位置を説明します。1〜2回の集中学習を目安としますが実測時間ではありません。

2. 前提知識の意味

関数は入力を出力に変換し、辞書は項目に名前を付けます。集合は重複を除くため繰り返し語の重みは増えません。IDは並べ替えても安定します。frozen dataclassは誤代入を防ぎますが、文書認証や集合の置換防止はしません。

ベースラインは単純で固定した比較対象です。保留は規則を満たさないことを意味し、答えの不存在を証明しません。トレースは候補の順位を記録します。流暢な生成や高得点も検索の正しさを保証しません。

3. アーキテクチャと契約

D1は再試行、D2は鍵更新、D3は制限付き事故記録です。CLIからanswer()へ渡し、型と長さを検証します。公開文書フィルタを採点とトレースより前に置き、制限IDの露出を防ぎます。これは教材の方針で、ログインやテナント認可ではありません。

出力はstatus、text、source、traceです。abstainではtextとsourceがnullになります。点数は無次元、sourceはIDです。不正入力はValueErrorにします。ネットワーク、永続化、副作用はありません。HTTP化する場合は認証、割当、期限、機密情報の除去が別途必要です。

参考設計:公開文書を絞ってから採点とトレースを作成。不正入力はエラー、十分な一致がなければ保留。
参考設計:公開文書を絞ってから採点とトレースを作成。不正入力はエラー、十分な一致がなければ保留。 原寸の図を見る

4. スコアの導出と計算

Qを正規化した検索語集合、Dを文書語集合とします。Qの被覆率なので非対称で、余分な文書語は罰しません。“timeout retry”はD1で2/2=1、D2で0/2=0です。D3は0点ではなく除外します。閾値0.5は等号を含みます。

“timeout missing”は1/2で返りますが全体の裏付けはありません。“connection stalled”は意味的に近くても0です。算術ではなく手法の限界です。閾値を下げると弱い一致も増え、上げても同義語は解決しません。被覆率を信頼度と呼びません。

IDQ ∩ Ds(Q,D)
D1timeout, retry2/2 = 1
D2∅0/2 = 0

5. 実装上の選択と限界

terms()は小文字化してASCII英数字を抽出します。モデルのtokenizerではなく、中日文分割、語幹処理、Unicode正規化等はしません。5言語教材は同じ英語データを使います。多言語システムには言語に合う解析と評価が必要です。

N文書、平均L文字なら毎回約N×L文字を解析し、O(N log N)で並べます。3文書向けです。語集合の事前計算から倒立索引へ進み、原文と一緒に版管理します。古い索引は削除した根拠を指す恐れがあります。IDで同点を処理し安定化します。

6. 基準を理解してから拡張する

BM25は頻度、希少性、長さを、密検索は表現の類似性を扱いますが、根拠の十分性は保証しません。生成器には許可文書だけを渡しIDを構造化して保持します。文書の命令を実行せず、引用を検証します。完全なRAGには取り込み、鮮度、認可、十分性も必要です。

全フレームワークを足す必要はありません。RAG総説で改善を一つ選び、SDE教材でモデル境界を理解し、状態付きツールが必要ならSREへ進みます。同じ未使用タスクで比較します。

7. 実践と検証

空フォルダにassistant.pyとtest_assistant.pyを保存します。Python 3.11以降のみ必要で依存追加、ダウンロード、APIキーは不要です。乱数を使わないのでseedも不要です。隠れた補助ファイルやリモートデータはありません。

assistant.py

ダウンロード assistant.py
"""Offline, deterministic retrieval baseline. Python 3.11+, standard library only."""
import json
import re
import sys
from dataclasses import dataclass

@dataclass(frozen=True)
class Document:
    id: str
    text: str
    audience: str = "public"

DOCS = (
    Document("D1", "Retry timeout requests with backoff."),
    Document("D2", "Rotate access keys every month."),
    Document("D3", "Private incident recovery password.", "restricted"),
)

def terms(text):
    return set(re.findall(r"[a-z0-9]+", text.lower()))

def answer(query, docs=DOCS, threshold=0.5):
    if not isinstance(query, str) or len(query) > 2000:
        raise ValueError("query must be a string of at most 2000 characters")
    if not 0 < threshold <= 1:
        raise ValueError("threshold must be in (0, 1]")
    if len({d.id for d in docs}) != len(docs):
        raise ValueError("duplicate document ID")
    q = terms(query)
    candidates = []
    for doc in docs:
        if doc.audience != "public":
            continue  # Filter before ranking or constructing the trace.
        score = len(q & terms(doc.text)) / len(q) if q else 0.0
        candidates.append((score, doc.id, doc.text))
    candidates.sort(key=lambda row: (-row[0], row[1]))
    trace = [{"id": d, "score": s} for s, d, _ in candidates]
    if not candidates or candidates[0][0] < threshold:
        return {"status": "abstain", "text": None, "source": None, "trace": trace}
    _, doc_id, text = candidates[0]
    return {"status": "evidence", "text": text, "source": doc_id, "trace": trace}

if __name__ == "__main__":
    query = " ".join(sys.argv[1:]) or "timeout retry"
    print(json.dumps(answer(query), indent=2))

test_assistant.py

ダウンロード test_assistant.py
import unittest
from assistant import answer, Document

class ContractTests(unittest.TestCase):
    def test_known(self):
        r = answer("timeout retry")
        self.assertEqual((r["status"], r["source"]), ("evidence", "D1"))
        self.assertEqual(r["trace"][0]["score"], 1.0)
    def test_unknown_and_empty(self):
        for query in ("", "quasar orbit", "日本語"):
            self.assertEqual(answer(query)["status"], "abstain")
    def test_no_private_trace(self):
        r = answer("private incident recovery password")
        self.assertEqual(r["status"], "abstain")
        self.assertNotIn("D3", str(r))
    def test_stable_tie(self):
        docs = (Document("B", "retry"), Document("A", "retry"))
        self.assertEqual(answer("retry", docs)["source"], "A")
    def test_boundaries(self):
        self.assertEqual(answer("timeout missing")["status"], "evidence")
        self.assertEqual(answer("timeout missing extra")["status"], "abstain")
        self.assertEqual(answer("retry", ())["status"], "abstain")
    def test_invalid(self):
        for query in (None, "x" * 2001):
            with self.assertRaises(ValueError): answer(query)
        with self.assertRaises(ValueError): answer("retry", threshold=0)
        with self.assertRaises(ValueError): answer("retry", (Document("A", "x"), Document("A", "y")))
    def test_lexical_failure_is_visible(self):
        # Semantically similar wording is intentionally NOT solved by this baseline.
        self.assertEqual(answer("connection stalled")["status"], "abstain")

if __name__ == "__main__":
    unittest.main()
python3 assistant.py "timeout retry"
python3 assistant.py "quasar orbit"
python3 -m unittest -v test_assistant.py

既定入力ではevidence、D1、、となりD3は出ません。7 testsとOKを確認します。“quasar orbit”はabstainでtext/sourceはnullです。時間は端末依存で性能主張ではありません。

文書、質問、権限を固定し、閾値だけ0.75へ変更します。戻して語集合を事前計算します。前者は挙動を変え、後者は維持すべきです。根拠、不十分な返却、保留を分け、開発用で調整し未使用セットで報告します。単体テストは本番品質の証明ではありません。

オリジナル面接演習:企業の実問題ではありません

なぜ1でも答えの証明ではないか

ヒント:語の被覆と意味を比べます。“do not retry timeout requests”は全語を含んでも否定します。否定や含意を扱わないため反例と根拠確認が必要です。

なぜトレースの前に絞り込むか

ヒント:診断も出力です。本文を隠してもIDや点数が漏れる可能性があります。先に除外すれば全出力から消えますが本人認証付き認可ではありません。

答えを変えずに高速化するには

ヒント:繰り返す処理を探します。不変版の語集合を保存し、点数と同点処理の一致を確認します。文書や解析変更で無効化し、等価性の後に速度を測ります。

採点:1は定義、2は計算、3は全テストの実行と説明、4は新しい反例と公平比較、5は独立拡張、契約維持、残る限界の説明です。職業資格ではありません。

参考資料と次の教材

AI/LMカリキュラム:学び、作り、説明する →
学習ガイドと授業の目次学習目標と確認

理解 → 実装 → 研究

目標:仕組みを説明し、例を再現し、失敗例を検証します。読むだけでは習得したことになりません。

予測・検証・根拠の記録

解答を開く前に結果を予測し、演習後に差異と応用テストを記録します。端末内に保存し、言語版間で共有します。

記録を開く/書き出す/消去する →

数学的確認の範囲は授業ごとに記録されています。論文の実証再現の証明ではありません。疑問点はメモに記録してください。 確認範囲