File Searchの回答に「何ページの、どの図か」まで添える ― 視覚引用メタデータで出典を検証可能にする

from google import genai
from google.genai import types
 
client = genai.Client(api_key="YOUR_GEMINI_API_KEY")
 
def build_cited_answer(response):
    """回答を文区間ごとに分解し、各区間に検証可能な出典を付ける。"""
    cand = response.candidates[0]
    meta = getattr(cand, "grounding_metadata", None)
    answer_text = cand.content.parts[0].text
 
    # メタデータが無い＝grounding されていない回答。出典なしで返す
    if meta is None or not getattr(meta, "grounding_supports", None):
        return [{"text": answer_text, "citations": []}]
 
    chunks = meta.grounding_chunks or []
    segments = []
 
    for sup in meta.grounding_supports:
        seg = sup.segment
        citations = []
        for idx in sup.grounding_chunk_indices:
            if idx >= len(chunks):
                continue  # 添字ずれの防御
            ctx = chunks[idx].retrieved_context
            citations.append({
                "title": ctx.title,
                "pages": getattr(ctx, "page_numbers", None),   # 例: [12]
                "media_id": getattr(ctx, "media_id", None),    # 例: "media/abc123"
            })
        segments.append({
            "text": answer_text[seg.start_index:seg.end_index],
            "citations": _dedupe_citations(citations),
        })
    return segments
 
 
def _dedupe_citations(citations):
    """同一ファイル・同一ページの引用を1つに畳む。"""
    seen, out = set(), []
    for c in citations:
        key = (c["title"], tuple(c["pages"] or []), c["media_id"])
        if key in seen:
            continue
        seen.add(key)
        out.append(c)
    return out

# build_cited_answer の出力例
[
  {
    "text": "トークンの有効期限は3600秒です。",
    "citations": [{"title": "design-spec.pdf", "pages": [12], "media_id": None}]
  },
  {
    "text": "ログイン後の遷移は次の図の通りです。",
    "citations": [{"title": "onboarding-flow.png", "pages": None, "media_id": "media/abc123"}]
  }
]

def resolve_media_thumbnail(client, media_id):
    """media_id から表示用の画像バイト列を取得する。失敗時は None。"""
    if not media_id:
        return None
    try:
        # ストアに保存された媒体を取得（取得APIはストア構成に依存）
        media = client.files.get(name=media_id)
        return media  # ファイル参照。UI 側で <img> の src に変換する
    except Exception as e:
        # 媒体が期限切れ・削除済みのケースは珍しくない
        print(f"media resolve failed for {media_id}: {e}")
        return None

def page_anchor_url(base_pdf_url, page_numbers):
    """page_numbers を PDF ビューアの該当ページURLに変換する。"""
    if not page_numbers:
        return base_pdf_url
    # 配列の先頭ページにジャンプ。範囲は別途レンジ表示する
    return f"{base_pdf_url}#page={page_numbers[0]}"
 
# 使用例
url = page_anchor_url("https://example.com/docs/design-spec.pdf", [12])
# → "https://example.com/docs/design-spec.pdf#page=12"