Skip to content

armgit / dub

Public Imported from GitHub
0

The modern link attribution platform. Loved by world-class engineering teams at Twilio, Zillow, Jobber, Vercel, Raycast, and more.

Use reciprocal rank fusion for Turbopuffer search branches

Rafic1d835f9a088
diff --git a/apps/web/lib/api/partners/search/providers/turbopuffer.ts b/apps/web/lib/api/partners/search/providers/turbopuffer.ts
index 0d54f51529..70ef727ad8 100644
--- a/apps/web/lib/api/partners/search/providers/turbopuffer.ts
+++ b/apps/web/lib/api/partners/search/providers/turbopuffer.ts
@@ -109,7 +109,7 @@ function serializeTurbopufferRow(
}
/**
- * Two ranked branches, unioned by the caller.
+ * Two ranked branches, rank-fused by the caller (see mergeBranchRows).
*
* The text branch treats the last token as a prefix so "john" reaches
* "johnson", matching how the Redis provider's $smart behaves. The n-gram
@@ -140,25 +140,34 @@ function buildQueryBranches(programId: string, query: string) {
return branches;
}
+// The standard reciprocal-rank-fusion constant: dampens the gap between
+// neighboring ranks so one branch's top result cannot drown out the other's.
+const RRF_RANK_CONSTANT = 60;
+
+/**
+ * Fuses the branches by rank (RRF) rather than by score. BM25 scores from
+ * different clauses are not comparable — the n-gram branch sums over many
+ * trigram terms and runs numerically hotter than the text branch — but rank
+ * positions are. Each document scores Σ 1/(60 + rank) across the branches it
+ * appears in, so a document found by both branches receives a contribution
+ * from each, and the raw `$dist` values are deliberately unused. Relies on
+ * each branch's rows arriving in the server's relevance order.
+ */
function mergeBranchRows(
branches: { rows?: { id: string | number; $dist?: number }[] }[],
limit: number,
) {
- const bestById = new Map<string, number>();
+ const scoreById = new Map<string, number>();
for (const branch of branches) {
- for (const row of branch.rows ?? []) {
+ (branch.rows ?? []).forEach((row, index) => {
const id = String(row.id);
- const score = row.$dist ?? 0;
- // Scores come from different BM25 clauses and are not directly
- // comparable; the higher one only decides ordering within the union.
- if (!bestById.has(id) || score > bestById.get(id)!) {
- bestById.set(id, score);
- }
- }
+ const contribution = 1 / (RRF_RANK_CONSTANT + index + 1);
+ scoreById.set(id, (scoreById.get(id) ?? 0) + contribution);
+ });
}
- return Array.from(bestById, ([id, score]) => ({ id, score }))
+ return Array.from(scoreById, ([id, score]) => ({ id, score }))
.sort(
(left, right) =>
right.score - left.score || left.id.localeCompare(right.id),
diff --git a/apps/web/tests/partners/turbopuffer-partner-search-provider.test.ts b/apps/web/tests/partners/turbopuffer-partner-search-provider.test.ts
index 2f7e13cafd..a94d038185 100644
--- a/apps/web/tests/partners/turbopuffer-partner-search-provider.test.ts
+++ b/apps/web/tests/partners/turbopuffer-partner-search-provider.test.ts
@@ -163,14 +163,17 @@ describe("Turbopuffer partner search provider", () => {
expect(queries).toHaveLength(1);
});
- it("unions branches, keeping the better score for a shared document", async () => {
+ it("fuses branches by rank, boosting documents found by both", async () => {
+ // Raw $dist values are incomparable across branches, so they must not
+ // decide the order: pge_2 carries the highest raw score but only one
+ // branch found it, while both branches found pge_1.
mocks.multiQuery.mockResolvedValue({
results: [
{ rows: [{ id: "pge_1", $dist: 0.4 }] },
{
rows: [
+ { id: "pge_2", $dist: 7.6 },
{ id: "pge_1", $dist: 0.9 },
- { id: "pge_2", $dist: 0.6 },
],
},
],
@@ -182,10 +185,27 @@ describe("Turbopuffer partner search provider", () => {
limit: 10,
});
- expect(hits).toEqual([
- { id: "pge_1", score: 0.9 },
- { id: "pge_2", score: 0.6 },
- ]);
+ expect(hits.map(({ id }) => id)).toEqual(["pge_1", "pge_2"]);
+ // RRF: rank 1 + rank 2 across branches vs rank 1 in one branch.
+ expect(hits[0].score).toBeCloseTo(1 / 61 + 1 / 62, 10);
+ expect(hits[1].score).toBeCloseTo(1 / 61, 10);
+ });
+
+ it("breaks cross-branch rank ties deterministically by ID", async () => {
+ mocks.multiQuery.mockResolvedValue({
+ results: [
+ { rows: [{ id: "pge_b", $dist: 9.5 }] },
+ { rows: [{ id: "pge_a", $dist: 0.2 }] },
+ ],
+ });
+
+ const { hits } = await createProvider().searchCandidates({
+ programId: "prog_test",
+ query: "examp",
+ limit: 10,
+ });
+
+ expect(hits.map(({ id }) => id)).toEqual(["pge_a", "pge_b"]);
});
it("never returns more than the requested limit", async () => {