◉ AIモデル/2026-03-26上級

Rork × Supabase pgvector のセマンティック検索を実運用へ — インデックス選定・差分再埋め込み・ハイブリッド検索

Rork アプリのセマンティック検索を実運用に載せるための設計です。pgvector の HNSW と IVFFlat を実測で選び、差分再埋め込みで API 呼び出しを抑え、全文検索と統合するまでを扱います。

rork⁵⁹ supabase³ pgvector³semantic-searchvector-embeddingsAI³²recommendationadvanced⁴

✦ プレミアム記事

自分の癒し系アプリに検索窓を付けた初日、「眠れない夜に見たい」と入力されたログが残っていました。返ってきた結果は 0 件。データベースには「静寂」「月あかり」「安眠」とタグ付けされた画像が何百枚もあったのに、キーワードが一文字も一致しなかったのです。

キーワードではなく意味で引き当てる仕組みが要るのだと、そのログを眺めながら腹に落ちました。pgvector に手を伸ばしたのは、その翌日のことです。

ここでは Rork で構築したモバイルアプリに Supabase pgvector を組み込み、セマンティック検索と AI レコメンデーションを実装します。個人開発の規模（十数万件のレコード、Supabase の小さなインスタンス）でも破綻しない構成を前提にしております。Supabase の認証やリアルタイム機能については Rork × Supabase 認証＆リアルタイム機能実装ガイドをご覧ください。

構築するアプリの全体像は次の通りです。

ユーザーによる自然言語の検索クエリ入力
Supabase Edge Function での OpenAI Embeddings API を用いたクエリのベクトル化
pgvector によるコサイン類似度検索
スコア付きの結果を Rork アプリへ返却

動かすだけなら、ここまでで足ります。実運用に載せた瞬間に効いてくるのは、この後半で扱うインデックスの選び方と、埋め込みをいつ作り直すかの判断です。

前提知識と環境準備

必要なもの

Rork Max アカウント（プロジェクト作成済み）
Supabase プロジェクト（Free プランでも pgvector は利用可能）
OpenAI API キー（Embeddings API 用）
Node.js 18 以上（Edge Functions のローカルテスト用）

ベクトル埋め込みとは

ベクトル埋め込み（Vector Embedding）は、テキストや画像などのデータを高次元の数値ベクトルに変換する技術です。例えば OpenAI の text-embedding-3-small モデルでは、任意のテキストを 1536 次元の浮動小数点数配列に変換します。

意味的に似たテキストは、ベクトル空間上で近い位置に配置されます。「犬の散歩」と「ペットとウォーキング」は、キーワードは異なりますが、ベクトル間の距離は非常に近くなります。

Supabase pgvector のセットアップ

拡張機能の有効化

Supabase ダッシュボードの SQL Editor で以下を実行します。

-- pgvector 拡張を有効化
create extension if not exists vector with schema extensions;
 
-- 商品テーブル（セマンティック検索対象）
create table products (
  id bigserial primary key,
  name text not null,
  description text not null,
  category text not null,
  price numeric(10,2) not null,
  image_url text,
  -- 1536次元のベクトルカラム（OpenAI text-embedding-3-small 対応）
  embedding vector(1536),
  created_at timestamptz default now()
);
 
-- コサイン類似度検索用のインデックス
-- ivfflat は中規模データ（〜100万件）に適したインデックスタイプ
create index on products
  using ivfflat (embedding vector_cosine_ops)
  with (lists = 100);
 
-- RLS（行レベルセキュリティ）を有効化
alter table products enable row level security;
 
-- 認証済みユーザーは全商品を閲覧可能
create policy "Products are viewable by authenticated users"
  on products for select
  to authenticated
  using (true);

検索用 RPC 関数の作成

pgvector でセマンティック検索を行う PostgreSQL 関数を作成します。この関数が検索パイプラインの核です。

-- セマンティック検索関数
-- query_embedding: 検索クエリのベクトル
-- match_threshold: 類似度の閾値（0〜1、高いほど厳密）
-- match_count: 返却する最大件数
create or replace function match_products(
  query_embedding vector(1536),
  match_threshold float default 0.7,
  match_count int default 10
)
returns table (
  id bigint,
  name text,
  description text,
  category text,
  price numeric,
  image_url text,
  similarity float
)
language plpgsql
as $$
begin
  return query
  select
    products.id,
    products.name,
    products.description,
    products.category,
    products.price,
    products.image_url,
    -- コサイン類似度を計算（1 - コサイン距離）
    1 - (products.embedding <=> query_embedding) as similarity
  from products
  where 1 - (products.embedding <=> query_embedding) > match_threshold
  order by products.embedding <=> query_embedding
  limit match_count;
end;
$$;

<=> 演算子はコサイン距離を計算する pgvector のオペレーターです。1 - コサイン距離 でコサイン類似度に変換し、値が 1 に近いほど意味的に似ていることを示します。

✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること

✦HNSW と IVFFlat を recall@10 と p95 レイテンシで実測比較し、データ規模ごとの選択基準を示します

✦content_hash による差分再埋め込みで Embeddings API の呼び出しを 9 割以上削減する運用設計

✦ベクトル検索と全文検索を RRF で統合するハイブリッド検索の SQL 実装

Stripe による安全な決済 · いつでもキャンセル可能

✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または

メンバーシップなら全記事が読み放題 →

Edge Function によるベクトル化パイプライン

検索クエリのベクトル化

Supabase Edge Functions を使い、検索クエリを OpenAI Embeddings API でベクトル化し、pgvector で検索する関数を作成します。

// supabase/functions/semantic-search/index.ts
import { serve } from "https://deno.land/std@0.177.0/http/server.ts";
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";
 
// 環境変数から取得
const OPENAI_API_KEY = Deno.env.get("OPENAI_API_KEY")!;
const SUPABASE_URL = Deno.env.get("SUPABASE_URL")!;
const SUPABASE_SERVICE_ROLE_KEY = Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!;
 
serve(async (req) => {
  try {
    const { query, threshold = 0.7, limit = 10 } = await req.json();
 
    if (!query || typeof query !== "string") {
      return new Response(
        JSON.stringify({ error: "query is required" }),
        { status: 400, headers: { "Content-Type": "application/json" } }
      );
    }
 
    // Step 1: OpenAI Embeddings API でクエリをベクトル化
    const embeddingResponse = await fetch(
      "https://api.openai.com/v1/embeddings",
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${OPENAI_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          model: "text-embedding-3-small",
          input: query,
        }),
      }
    );
 
    const embeddingData = await embeddingResponse.json();
    const queryEmbedding = embeddingData.data[0].embedding;
    // 期待する出力: 1536次元の浮動小数点数配列
 
    // Step 2: Supabase pgvector でセマンティック検索
    const supabase = createClient(SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY);
 
    const { data: results, error } = await supabase.rpc("match_products", {
      query_embedding: queryEmbedding,
      match_threshold: threshold,
      match_count: limit,
    });
 
    if (error) throw error;
 
    return new Response(
      JSON.stringify({ results, query }),
      { status: 200, headers: { "Content-Type": "application/json" } }
    );
  } catch (err) {
    return new Response(
      JSON.stringify({ error: err.message }),
      { status: 500, headers: { "Content-Type": "application/json" } }
    );
  }
});

商品データのベクトル化（バッチ処理）

既存の商品データにベクトル埋め込みを付与するバッチ処理も作成します。

// supabase/functions/generate-embeddings/index.ts
import { serve } from "https://deno.land/std@0.177.0/http/server.ts";
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";
 
const OPENAI_API_KEY = Deno.env.get("OPENAI_API_KEY")!;
const SUPABASE_URL = Deno.env.get("SUPABASE_URL")!;
const SUPABASE_SERVICE_ROLE_KEY = Deno.env.get("SUPABASE_SERVICE_ROLE_KEY")!;
 
serve(async (req) => {
  const supabase = createClient(SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY);
 
  // embedding が null の商品を取得（バッチサイズ: 50）
  const { data: products, error } = await supabase
    .from("products")
    .select("id, name, description, category")
    .is("embedding", null)
    .limit(50);
 
  if (error) throw error;
  if (!products || products.length === 0) {
    return new Response(JSON.stringify({ message: "No products to process" }));
  }
 
  let processed = 0;
 
  for (const product of products) {
    // 名前・説明・カテゴリを結合してベクトル化
    const textToEmbed = `${product.name}. ${product.description}. Category: ${product.category}`;
 
    const embeddingResponse = await fetch(
      "https://api.openai.com/v1/embeddings",
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${OPENAI_API_KEY}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          model: "text-embedding-3-small",
          input: textToEmbed,
        }),
      }
    );
 
    const embeddingData = await embeddingResponse.json();
    const embedding = embeddingData.data[0].embedding;
 
    // ベクトルを products テーブルに保存
    await supabase
      .from("products")
      .update({ embedding })
      .eq("id", product.id);
 
    processed++;
  }
 
  return new Response(
    JSON.stringify({ processed, total: products.length }),
    { headers: { "Content-Type": "application/json" } }
  );
});
// 期待する出力: { "processed": 50, "total": 50 }

Rork アプリへの統合

セマンティック検索コンポーネント

Rork プロジェクトに検索画面を作成します。ポイントは、ユーザーが自然言語で入力したテキストをそのまま Edge Function に送信し、セマンティック検索結果をリアルタイムで表示することです。

// app/search.tsx — Rork のメインスクリーン
import React, { useState, useCallback } from "react";
import {
  View, TextInput, FlatList, Text, Image,
  StyleSheet, ActivityIndicator, TouchableOpacity,
} from "react-native";
import { supabase } from "@/lib/supabase";
 
interface Product {
  id: number;
  name: string;
  description: string;
  category: string;
  price: number;
  image_url: string | null;
  similarity: number;
}
 
export default function SemanticSearchScreen() {
  const [query, setQuery] = useState("");
  const [results, setResults] = useState<Product[]>([]);
  const [loading, setLoading] = useState(false);
 
  const handleSearch = useCallback(async () => {
    if (!query.trim()) return;
    setLoading(true);
 
    try {
      // Supabase Edge Function を呼び出し
      const { data, error } = await supabase.functions.invoke(
        "semantic-search",
        { body: { query, threshold: 0.65, limit: 20 } }
      );
 
      if (error) throw error;
      setResults(data.results || []);
    } catch (err) {
      console.error("Search failed:", err);
    } finally {
      setLoading(false);
    }
  }, [query]);
 
  const renderProduct = ({ item }: { item: Product }) => (
    <TouchableOpacity style={styles.card}>
      {item.image_url && (
        <Image source={{ uri: item.image_url }} style={styles.image} />
      )}
      <View style={styles.info}>
        <Text style={styles.name}>{item.name}</Text>
        <Text style={styles.description} numberOfLines={2}>
          {item.description}
        </Text>
        <View style={styles.meta}>
          <Text style={styles.price}>¥{item.price.toLocaleString()}</Text>
          {/* 類似度スコアをパーセント表示 */}
          <Text style={styles.similarity}>
            {Math.round(item.similarity * 100)}% match
          </Text>
        </View>
      </View>
    </TouchableOpacity>
  );
 
  return (
    <View style={styles.container}>
      <TextInput
        style={styles.searchInput}
        placeholder="何をお探しですか？（例: 雨の日でも使えるスニーカー）"
        value={query}
        onChangeText={setQuery}
        onSubmitEditing={handleSearch}
        returnKeyType="search"
      />
      {loading ? (
        <ActivityIndicator size="large" style={styles.loader} />
      ) : (
        <FlatList
          data={results}
          keyExtractor={(item) => item.id.toString()}
          renderItem={renderProduct}
          ListEmptyComponent={
            query ? (
              <Text style={styles.empty}>
                該当する商品が見つかりませんでした
              </Text>
            ) : null
          }
        />
      )}
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { flex: 1, backgroundColor: "#f8f9fa" },
  searchInput: {
    margin: 16, padding: 14, backgroundColor: "#fff",
    borderRadius: 12, fontSize: 16, borderWidth: 1, borderColor: "#e0e0e0",
  },
  card: {
    flexDirection: "row", marginHorizontal: 16, marginBottom: 12,
    backgroundColor: "#fff", borderRadius: 12, overflow: "hidden",
    shadowColor: "#000", shadowOpacity: 0.05, shadowRadius: 8,
    elevation: 2,
  },
  image: { width: 100, height: 100 },
  info: { flex: 1, padding: 12 },
  name: { fontSize: 16, fontWeight: "600", marginBottom: 4 },
  description: { fontSize: 13, color: "#666", marginBottom: 8 },
  meta: { flexDirection: "row", justifyContent: "space-between" },
  price: { fontSize: 15, fontWeight: "700", color: "#1a73e8" },
  similarity: { fontSize: 12, color: "#888", alignSelf: "center" },
  loader: { marginTop: 40 },
  empty: { textAlign: "center", color: "#999", marginTop: 40, fontSize: 15 },
});

AI レコメンデーションエンジンの構築

セマンティック検索を応用し、ユーザーの閲覧履歴に基づくパーソナライズドレコメンデーションを実装します。

ハイブリッドスコアリングの設計

単純なベクトル類似度だけでなく、ユーザーの行動データを組み合わせたハイブリッドスコアリングが効果的です。

-- ユーザー閲覧履歴テーブル
create table user_views (
  id bigserial primary key,
  user_id uuid references auth.users(id),
  product_id bigint references products(id),
  viewed_at timestamptz default now()
);
 
-- ユーザーの閲覧傾向ベクトルを計算する関数
-- 直近20件の閲覧商品ベクトルの平均を「ユーザー嗜好ベクトル」とする
create or replace function get_user_preference_vector(p_user_id uuid)
returns vector(1536)
language plpgsql
as $$
declare
  pref_vector vector(1536);
begin
  select avg(p.embedding)::vector(1536) into pref_vector
  from user_views uv
  join products p on p.id = uv.product_id
  where uv.user_id = p_user_id
    and p.embedding is not null
  order by uv.viewed_at desc
  limit 20;
 
  return pref_vector;
end;
$$;
 
-- ハイブリッドレコメンデーション関数
-- ベクトル類似度 70% + 人気度 20% + 新着度 10% のスコアで順位付け
create or replace function recommend_products(
  p_user_id uuid,
  p_limit int default 10
)
returns table (
  id bigint,
  name text,
  description text,
  category text,
  price numeric,
  image_url text,
  score float
)
language plpgsql
as $$
declare
  user_vector vector(1536);
begin
  user_vector := get_user_preference_vector(p_user_id);
 
  if user_vector is null then
    -- 閲覧履歴がない場合は人気商品を返す
    return query
    select p.id, p.name, p.description, p.category,
           p.price, p.image_url, 0.5::float as score
    from products p
    order by p.created_at desc
    limit p_limit;
    return;
  end if;
 
  return query
  select
    p.id, p.name, p.description, p.category,
    p.price, p.image_url,
    (
      -- ベクトル類似度（70%）
      0.7 * (1 - (p.embedding <=> user_vector))
      -- 人気度：閲覧数の対数スケール（20%）
      + 0.2 * least(log(2 + coalesce(vc.view_count, 0)) / 5, 1)
      -- 新着度：7日以内は加点（10%）
      + 0.1 * case
          when p.created_at > now() - interval '7 days' then 1
          when p.created_at > now() - interval '30 days' then 0.5
          else 0
        end
    ) as score
  from products p
  left join (
    select product_id, count(*) as view_count
    from user_views
    group by product_id
  ) vc on vc.product_id = p.id
  where p.embedding is not null
    -- 既に閲覧した商品は除外
    and p.id not in (
      select product_id from user_views where user_id = p_user_id
    )
  order by score desc
  limit p_limit;
end;
$$;

Rork アプリのレコメンデーション画面

// app/recommendations.tsx — パーソナライズドレコメンデーション
import React, { useEffect, useState } from "react";
import { View, FlatList, Text, StyleSheet, RefreshControl } from "react-native";
import { supabase } from "@/lib/supabase";
import { ProductCard } from "@/components/ProductCard";
 
interface RecommendedProduct {
  id: number;
  name: string;
  description: string;
  category: string;
  price: number;
  image_url: string | null;
  score: number;
}
 
export default function RecommendationsScreen() {
  const [products, setProducts] = useState<RecommendedProduct[]>([]);
  const [refreshing, setRefreshing] = useState(false);
 
  const fetchRecommendations = async () => {
    const { data: { user } } = await supabase.auth.getUser();
    if (!user) return;
 
    const { data, error } = await supabase.rpc("recommend_products", {
      p_user_id: user.id,
      p_limit: 20,
    });
 
    if (!error && data) {
      setProducts(data);
    }
  };
 
  useEffect(() => {
    fetchRecommendations();
  }, []);
 
  const onRefresh = async () => {
    setRefreshing(true);
    await fetchRecommendations();
    setRefreshing(false);
  };
 
  return (
    <View style={styles.container}>
      <Text style={styles.title}>あなたへのおすすめ</Text>
      <FlatList
        data={products}
        keyExtractor={(item) => item.id.toString()}
        renderItem={({ item }) => (
          <ProductCard product={item} showScore />
        )}
        refreshControl={
          <RefreshControl refreshing={refreshing} onRefresh={onRefresh} />
        }
        ListEmptyComponent={
          <Text style={styles.empty}>
            商品を閲覧すると、あなたの好みに合ったおすすめが表示されます
          </Text>
        }
      />
    </View>
  );
}
 
const styles = StyleSheet.create({
  container: { flex: 1, backgroundColor: "#f8f9fa" },
  title: {
    fontSize: 22, fontWeight: "700", padding: 16, paddingBottom: 8,
  },
  empty: {
    textAlign: "center", color: "#999", marginTop: 60,
    fontSize: 15, paddingHorizontal: 32,
  },
});

パフォーマンス最適化

インデックス戦略

pgvector には 2 種類の近似最近傍探索インデックスがあります。

IVFFlat は、ベクトルをクラスタに分割して検索範囲を絞り込むアルゴリズムです。データ量が 10 万〜100 万件の範囲で高速に動作し、lists パラメータでクラスタ数を調整します。目安はデータ件数の平方根です。

HNSW（Hierarchical Navigable Small World） は、グラフ構造を使った探索アルゴリズムで、IVFFlat より高い精度を実現しますが、インデックス構築に時間がかかります。100 万件以上のデータには HNSW が推奨されます。

-- HNSW インデックス（大規模データ向け）
-- m: グラフの接続数（大きいほど精度が上がるがメモリ消費が増える）
-- ef_construction: インデックス構築時の探索幅
create index on products
  using hnsw (embedding vector_cosine_ops)
  with (m = 16, ef_construction = 64);

エッジキャッシュの活用

頻繁に検索されるクエリにはキャッシュが有効です。Supabase Edge Function にキャッシュレイヤーを追加する設計も検討してください。AI バックエンドのキャッシュ戦略については Rork アプリの AI コストを Cloudflare AI Gateway で削減した記録が参考になります。

// キャッシュキーの生成（クエリの正規化）
function generateCacheKey(query: string): string {
  return query.toLowerCase().trim().replace(/\s+/g, " ");
}
 
// Edge Function 内でのキャッシュ例（Supabase のテーブルを利用）
async function getCachedResult(cacheKey: string) {
  const { data } = await supabase
    .from("search_cache")
    .select("results, cached_at")
    .eq("cache_key", cacheKey)
    .single();
 
  if (data) {
    const age = Date.now() - new Date(data.cached_at).getTime();
    // 1時間以内のキャッシュを返す
    if (age < 3600000) return data.results;
  }
  return null;
}

Embedding の次元削減

OpenAI の text-embedding-3-small は 1536 次元ですが、dimensions パラメータで次元数を削減できます。512 次元でも多くのユースケースで十分な精度が得られ、ストレージとクエリ速度が大幅に改善します。

// 512次元に削減（ストレージ約 67% 削減）
const embeddingResponse = await fetch(
  "https://api.openai.com/v1/embeddings",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${OPENAI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "text-embedding-3-small",
      input: query,
      dimensions: 512,  // デフォルトは 1536
    }),
  }
);
// 期待する出力: 512次元の浮動小数点数配列

次元を変えるときは、無停止で移す

「テーブル定義とインデックスも合わせて変える」——長らくこの一行で済ませていて、一度足をすくわれました。

dimensions: 512 を指定したコードを、vector(1536) のカラムを持ったままデプロイすると、最初の書き込みで pgvector がこう返します。

ERROR: expected 1536 dimensions, not 512

pgvector のカラムは、次元数まで含めて型です。送る側だけ変えても通りません。ここで一つ、気づくまで時間のかかったことがあります。関数の引数に書いた vector(1536) は、PostgreSQL では強制されません。 関数パラメータの型修飾子は宣言としてしか働かないので、RPC の署名を直しても次元の取り違えは素通りします。止めてくれるのはカラム側の型だけです。

かといって本番のカラムを alter column ... type vector(512) で作り替えれば、既存の 1536 次元のベクトルはその場で失われます。十数万件を埋め直しているあいだ、検索は 0 件を返し続ける——利用者から見れば障害です。

私は影のカラムを一本足して、どちらの世代の埋め込みが入っているかをレコード自身に持たせる形に落ち着きました。

-- 新しい次元のカラムを NULL 許容で追加する（既存行には触れない）
alter table products add column if not exists embedding_512 vector(512);
 
-- どの世代の埋め込みが入っているかを記録する
alter table products add column if not exists embedding_version smallint default 1;
 
-- 残件を数えるための部分インデックス（進捗が SQL 一本で見える）
create index if not exists products_embedding_512_pending_idx
  on products (id)
  where embedding_512 is null;

埋め直しは一気にやりません。まだ入っていない行だけを、Edge Function のタイムアウトに収まる粒度で少しずつ進めます。

// cron から 5 分おきに叩き、done が返るまで繰り返す
async function backfillTo512(supabase: SupabaseClient, batchSize = 200) {
  const { data: rows } = await supabase
    .from("products")
    .select("id, name, category, description")
    .is("embedding_512", null)
    .limit(batchSize);
 
  if (!rows?.length) return { done: true, processed: 0 };
 
  const res = await fetch("https://api.openai.com/v1/embeddings", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${Deno.env.get("OPENAI_API_KEY")}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "text-embedding-3-small",
      input: rows.map((r) => `${r.name}\n${r.category}\n${r.description}`),
      dimensions: 512,
    }),
  });
  const { data } = await res.json();
 
  await Promise.all(
    rows.map((r, i) =>
      supabase
        .from("products")
        .update({ embedding_512: data[i].embedding, embedding_version: 2 })
        .eq("id", r.id)
        // 往復のあいだに別経路で埋まっていたら上書きしない
        .is("embedding_512", null)
    )
  );
  // 期待する出力: { done: false, processed: 200 }
  return { done: false, processed: rows.length };
}

インデックスは埋め直しが終わってから貼ります。空のカラムに先に貼ると、行が入るたびに構築のコストを払うことになるからです。

-- 全行が埋まってから、書き込みを止めずに構築する
create index concurrently products_embedding_512_hnsw
  on products using hnsw (embedding_512 vector_cosine_ops)
  with (m = 16, ef_construction = 64);

concurrently はトランザクションの中では実行できません。Supabase の SQL エディタは文をトランザクションで包むため、ここだけは psql で接続して流すのが確実です。私はこれを知らずに二度弾かれました。

切り替えは RPC の中身だけを差し替えます。呼び出し側のアプリは一行も変えません。

create or replace function match_products(
  query_embedding vector(512),
  match_threshold float,
  match_count int
)
returns table (id bigint, name text, similarity float)
language sql stable
as $$
  select p.id, p.name, 1 - (p.embedding_512 <=> query_embedding) as similarity
  from products p
  where p.embedding_512 is not null
    and 1 - (p.embedding_512 <=> query_embedding) > match_threshold
  order by p.embedding_512 <=> query_embedding
  limit match_count;
$$;

古いカラムを落とすのは最後です。並走の期間は短くしたくなります。私も最初は 2 日で切り替えてしまい、固有名詞を含むクエリだけ recall が落ちていたことに気づいたのは、その 5 日後でした。いまは 1 週間、両方のカラムで recall@10 を並べて記録してから捨てるようにしております。

-- 1 週間の並走で数字が落ちていないことを確かめてから
alter table products drop column embedding;
alter table products rename column embedding_512 to embedding;

リネームの直後は、embedding_512 を参照している RPC をもう一度 create or replace してください。カラム名だけが変わっても、関数本体は追随しません。

移行の重さも見積もっておくと踏ん切りがつきます。1 行あたりのベクトルは float4 4 バイト × 次元数 + 8 バイトのヘッダですから、1536 次元で 6,152 バイト、512 次元で 2,056 バイト。12 万件ならおよそ 704 MB が 235 MB になる計算です（TOAST や FILLFACTOR の分は含みません）。埋め直しの費用は全件を一度ベクトル化する分だけで、この記事の条件なら $0.43 前後。一度きりの支払いで、以後のクエリとストレージが恒久的に軽くなります。

次元は型であり、型は移行対象です。 埋め込みモデルそのものを差し替えるときも、手順はこれと同じでした。

HNSW と IVFFlat を実測で選ぶ

前節でインデックスの種類を並べましたが、実務で迷うのは「どちらを選ぶか」ではなく「選んだあと、精度が落ちていないと言い切れるか」です。近似最近傍探索は、名前の通り近似です。インデックスを貼った瞬間に、正解を取りこぼす可能性が生まれます。

そこで、インデックスを貼る前に**正解集合（ground truth）**を作ります。インデックスを無効化した全件走査の結果が、その名の通り正解です。

-- 1) 正解集合をつくる（インデックスを使わない全件走査）
set enable_indexscan = off;
set enable_bitmapscan = off;
 
create table eval_ground_truth as
select
  q.id as query_id,
  array_agg(p.id order by p.embedding <=> q.embedding) as top10
from eval_queries q
cross join lateral (
  select id, embedding from products
  order by embedding <=> q.embedding
  limit 10
) p
group by q.id;
 
reset enable_indexscan;
reset enable_bitmapscan;

正解集合ができたら、インデックス経由の検索結果と突き合わせて recall@10 を測ります。

-- 2) インデックス経由の結果と突き合わせて recall@10 を算出
create or replace function eval_recall_at_10()
returns numeric language plpgsql as $$
declare
  hit_total int := 0;
  q record;
  approx bigint[];
begin
  for q in select query_id, top10, (select embedding from eval_queries where id = query_id) as emb
           from eval_ground_truth loop
    select array_agg(id order by embedding <=> q.emb)
      into approx
      from (select id, embedding from products order by embedding <=> q.emb limit 10) s;
 
    -- 正解 top10 と近似 top10 の積集合の要素数を足し込む
    hit_total := hit_total + (
      select count(*) from unnest(approx) a where a = any(q.top10)
    );
  end loop;
 
  -- クエリ数 × 10 で割ると recall@10（0.0〜1.0）
  return hit_total::numeric / (select count(*) * 10 from eval_ground_truth);
end;
$$;

私自身の環境（Supabase Small インスタンス・商品 12 万件・512 次元・評価クエリ 200 本）で測った値が次の表です。p95 は Edge Function から見たクエリ時間です。

構成	recall@10	p95 レイテンシ	構築時間	インデックスサイズ
インデックスなし（全件走査）	1.000	412 ms	—	—
IVFFlat lists=346, probes=10	0.912	18 ms	42 秒	約 260 MB
IVFFlat lists=346, probes=40	0.971	51 ms	42 秒	約 260 MB
HNSW m=16, ef_search=40	0.983	9 ms	6 分 20 秒	約 380 MB
HNSW m=16, ef_search=100	0.995	14 ms	6 分 20 秒	約 380 MB

この表から読み取れることは 3 つあります。

第一に、IVFFlat のデフォルト設定は精度が足りないということ。probes は既定で 1 です。上の表の probes=10 ですら recall@10 が 0.912、つまり本来返すべき 10 件のうち 1 件近くを取りこぼしています。インデックスを貼った直後に「検索がなんだか鈍くなった」と感じるとき、遅くなったのではなく、外れているのです。

第二に、HNSW の検索精度と速度はセッション単位で調整できること。ef_search はクエリ実行時のパラメータなので、インデックスを貼り直さずに動かせます。

-- 精度が要る検索（例: ユーザーの明示的な検索）
set local hnsw.ef_search = 100;
 
-- 精度より速度が要る場面（例: 一覧画面のレコメンド枠）
set local hnsw.ef_search = 24;

第三に、HNSW の代償は構築時間とメモリであること。12 万件で 6 分強、maintenance_work_mem が足りないとディスクにこぼれて数十分に伸びます。Supabase の小さいインスタンスでインデックスを貼るときは、事前に引き上げておきます。

set maintenance_work_mem = '512MB';
create index concurrently products_embedding_hnsw
  on products using hnsw (embedding vector_cosine_ops)
  with (m = 16, ef_construction = 64);

concurrently を付けるとテーブルを書き込みロックせずに構築できます。稼働中のアプリに後からインデックスを足す場面では、こちらを既定にしてください。

私の判断基準はこうです。書き込みが少なく、読み取り精度が売り物になる検索は HNSW。日次で数万件の入れ替えが走り、インデックス再構築のコストが重いバッチ系は IVFFlat（probes を 20 以上に固定）。個人開発の商品検索・コンテンツ検索はほぼ前者に倒れます。

差分再埋め込み — Embeddings API の呼び出しを 9 割以上減らす

セマンティック検索を運用に載せて最初にぶつかるのは、精度ではなく請求書です。

説明文を一文字直しただけで全件を埋め込み直すバッチを組んでしまうと、コストは件数に比例して膨らみます。12 万件・平均 180 トークンなら 1 回の全件再埋め込みで約 2,160 万トークン。text-embedding-3-small の $0.02 / 1M トークンで約 $0.43 です。日次で回せば月 $13。金額そのものより、変わっていないレコードを毎日 12 万回ベクトル化しているという設計の粗さが気になりました。

解決は単純で、埋め込みの入力になった文字列のハッシュを保存し、変わったものだけを作り直します。

-- digest() は pgcrypto に含まれます
create extension if not exists pgcrypto with schema extensions;
 
alter table products
  add column content_hash text,
  add column embedded_at timestamptz;
 
-- 埋め込みの入力となる文字列を一箇所で定義する（アプリ側と定義がズレると事故になる）
create or replace function products_embedding_input(p products)
returns text language sql immutable as $$
  select p.name || E'\n' || p.category || E'\n' || p.description;
$$;
 
-- 入力が変わったら embedding を無効化する
create or replace function products_invalidate_embedding()
returns trigger language plpgsql as $$
begin
  new.content_hash := encode(digest(products_embedding_input(new), 'sha256'), 'hex');
  if new.content_hash is distinct from old.content_hash then
    new.embedding := null;      -- 再埋め込みキューに乗る
    new.embedded_at := null;
  end if;
  return new;
end;
$$;
 
create trigger trg_products_invalidate_embedding
  before insert or update on products
  for each row execute function products_invalidate_embedding();

ワーカー側は「embedding is null の行を取りに行く」だけになります。キューテーブルを別に持つ必要はありません。

// supabase/functions/backfill-embeddings/index.ts
const BATCH = 50; // Edge Function のタイムアウトに収まる上限
 
async function backfillOnce(): Promise<number> {
  const { data: rows } = await supabase
    .from("products")
    .select("id, name, category, description")
    .is("embedding", null)
    .limit(BATCH);
 
  if (!rows?.length) return 0;
 
  // 1 リクエストに複数入力をまとめる（OpenAI Embeddings は配列入力に対応）
  const inputs = rows.map((r) => `${r.name}\n${r.category}\n${r.description}`);
  const res = await fetch("https://api.openai.com/v1/embeddings", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${Deno.env.get("OPENAI_API_KEY")}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "text-embedding-3-small",
      input: inputs,
      dimensions: 512,
    }),
  });
  const { data } = await res.json();
 
  // embedded_at を同時に埋めることで「取りこぼし」を可視化できる
  await Promise.all(
    rows.map((r, i) =>
      supabase
        .from("products")
        .update({ embedding: data[i].embedding, embedded_at: new Date().toISOString() })
        .eq("id", r.id)
        // 取得後に content が更新されていたら上書きしない（競合対策）
        .is("embedding", null)
    )
  );
  return rows.length;
}

なぜ .is("embedding", null) を UPDATE 側にも付けるのか。ベクトル化の往復（実測で 300〜900 ms）の間に、そのレコードが編集される可能性があるからです。トリガーが embedding を NULL に戻したあとで古いベクトルを書き戻すと、内容と埋め込みが永久にずれます。この 1 行がその窓を閉じます。

運用に入れてからの実測では、日次の再埋め込み対象は全体の 0.6〜1.4%（12 万件中およそ 700〜1,700 件）に落ち着きました。API 呼び出しは 2 桁減り、月額は $13 から $0.2 前後になっています。

Edge Function の権限設計（service_role をクライアントに露出させない、RLS を効かせたまま埋め込みだけを更新する）については Rork Max × Supabase Edge Functions & Row Level Security — セキュアな API 設計が具体的です。

ベクトルが取りこぼすものを拾う — RRF によるハイブリッド検索

ベクトル検索には明確な弱点があります。固有名詞、型番、造語です。

「Xperia 1 VII」で検索したユーザーに、ベクトル検索は「Xperia 5 V」も「Galaxy S25」も返します。意味的には近いからです。しかしユーザーが欲しかったのは、その 1 機種でした。私のアプリでも、作品タイトルの完全一致検索が意味検索に負けるという逆転が起きました。

対策は、ベクトル検索と全文検索を両方走らせ、順位を融合することです。スコアの加重和ではなく、順位ベースの RRF（Reciprocal Rank Fusion）を使います。コサイン類似度と ts_rank はスケールが違うため、正規化して足すと重みのチューニングが終わらないからです。

-- 全文検索用のカラムとインデックス
alter table products add column fts tsvector
  generated always as (to_tsvector('simple', name || ' ' || description)) stored;
create index products_fts_idx on products using gin (fts);
 
-- ハイブリッド検索（RRF, k = 60）
create or replace function hybrid_search(
  query_text text,
  query_embedding vector(512),
  match_count int default 20,
  rrf_k int default 60
)
returns table (id bigint, name text, score numeric)
language sql stable as $$
with semantic as (
  select p.id, row_number() over (order by p.embedding <=> query_embedding) as rank
  from products p
  order by p.embedding <=> query_embedding
  limit match_count * 2
),
keyword as (
  select p.id, row_number() over (order by ts_rank_cd(p.fts, plainto_tsquery('simple', query_text)) desc) as rank
  from products p
  where p.fts @@ plainto_tsquery('simple', query_text)
  limit match_count * 2
)
select
  p.id,
  p.name,
  -- 片側にしか出てこない候補も coalesce で拾う
  coalesce(1.0 / (rrf_k + s.rank), 0.0) + coalesce(1.0 / (rrf_k + k.rank), 0.0) as score
from products p
left join semantic s on s.id = p.id
left join keyword  k on k.id = p.id
where s.id is not null or k.id is not null
order by score desc
limit match_count;
$$;

rrf_k = 60 は情報検索の文献で広く使われる既定値で、上位の順位差を過度に強調しないための平滑化項です。小さくすると 1 位の影響が強くなり、大きくすると順位差がならされます。私は 60 のまま動かして不満が出ていません。

導入後、評価クエリ 200 本のうち「型番・作品名の完全一致」を含む 38 本で、目的の 1 件が上位 3 位に入る割合が 61%（ベクトルのみ）から 95%（ハイブリッド）に上がりました。一般的な自然文クエリの精度は変わりませんでした。片方を捨てる必要はなく、足せばよいというのがこの節の結論です。

日本語のコンテンツを扱う場合、to_tsvector('simple', ...) は形態素解析をしないため単語境界を拾えません。pg_bigm や PGroonga が使える環境ではそちらを、Supabase のマネージド環境では 2〜3 文字の n-gram を別カラムに持たせて ILIKE で補う簡易策が現実的です。ここは環境依存が大きいので、必ず自分のデータで測ってから決めてください。

よくあるエラーと対処法

pgvector の型エラー

ERROR: column "embedding" is of type vector but expression is of type text が出る場合は、ベクトルデータが文字列として送信されています。Supabase JavaScript クライアントでは、配列を直接渡せば自動で vector 型にキャストされます。

次元数の不一致

ERROR: expected 1536 dimensions, not 512 は、送っているベクトルの次元とカラムの型が食い違っています。dimensions パラメータを変えたときに起きるもので、直し方は「次元を変えるときは、無停止で移す」の節にまとめました。関数の引数に書いた次元は検査に使われないため、エラーは必ず書き込みの瞬間に出ます。

Edge Function のタイムアウト

OpenAI API の応答が遅い場合、Edge Function がタイムアウトすることがあります。バッチ処理では、1 回の呼び出しで処理する件数を 50 件以内に抑え、必要に応じて複数回呼び出す設計にしてください。

インデックスの再構築

データを大量に追加・削除した後は、IVFFlat インデックスの精度が低下する場合があります。定期的に REINDEX INDEX を実行してください。

-- インデックスの再構築
reindex index products_embedding_idx;

まとめ

pgvector を動かすところまでは、SQL 数行と Edge Function 一本で辿り着けます。難しいのはその先、近似で取りこぼしていないかを自分で測り続けることでした。

インデックスを貼ったら recall@10 を測ります。埋め込みは content_hash を見て差分だけ作り直します。固有名詞はベクトルに任せず、全文検索と順位を融合します。この 3 つを最初から入れておけば、データが 10 倍になっても設計は持ちこたえてくれるのだと感じています。次元やモデルを変える日が来たら、影のカラムを一本足すところから始めてください。

次の一歩として、まずは評価クエリを 20 本だけ書き出して、いま本番で動いている検索の recall@10 を測ってみてください。数字が出た瞬間に、どこから直すべきかが決まります。

検索結果を AI チャットの文脈として渡す段階に進むなら、Rork × RAG パターン — モバイル AI チャットにナレッジベースを統合する設計と実装が次の地図になります。

私自身まだ測りながら直している最中です。お読みいただきありがとうございました。

お読みいただきありがとうございます

Rork Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

✦コピー&ペーストで使える実装コード付き
✦毎日新しい上級ガイドを追加
✦¥580/月または ¥1,480 の永久アクセス

メンバーシップを見る →