Debug comparing raw tokens without vectors in the article embedding search

Do not start with a speculative fix for the article embedding search. Force the failure on purpose, save the before output, then change one cause at a time. Retries are allowed only for transient conditions—not for bad input that will fail forever on embedding-api-lab.

for (let attempt = 0; attempt <= maxRetries; attempt++) {
  try { return await operation(signal); }
  catch (error) {
    const failure = classify(error);
    if (!failure.retryable || attempt === maxRetries) throw failure;
    await sleep(jitteredBackoff(attempt), signal);
  }
}
throw new Error("unreachable");

Expected evidence: The query “reset password” returns the password-reset article first with a finite score.. If you cannot reproduce on demand, you do not yet control the failure mode for embedding-api-lab.

After repair, rerun the exact reproduction command. Keep the failing fixture as a regression seed for the observability page. For the semantic search over support articles, remember the claim you are restoring: query embedding + article embeddings produce a stable top-1 for the fixture question.

Store a one-command reproduction for: comparing raw tokens without vectors, or dimension mismatch. The command should use three short support articles + one gold query or a minimal mutant of it. Paste the failing output into notes/failure-before.txt (or your shell scrollback as copied text). After the fix, paste notes/failure-after.txt and keep both.

Retries belong only on transient faults. If the failure is bad input, a bad allowlist, or a logic bug in the article embedding search, retrying will amplify cost without repairing trust around rank articles by cosine similarity to an embedded query.

Classify the failure as prevent, detect, contain, or recover—using this lab’s language, not a generic poster. For embedding-api-lab, the first fix should usually be detect+prevent at the boundary, because comparing raw tokens without vectors, or dimension mismatch is cheaper to stop early than to explain in production prose.

At the debugging stage for embedding-api-lab, the job is narrower than finishing a product demo. You are creating one progressive evidence piece about three short support articles + one gold query that later pages inherit without redefining success. Keep that fixture small enough to inspect by hand, keep outputs copy-pasteable as text, and refuse to narrate this baseline as if it were a production SLA: keyword overlap ranking on the same articles.

For this page specifically, success looks like before/after evidence for the characteristic failure while still centering the user decision to rank articles by cosine similarity to an embedded query. If you cannot point to a file, command, or assertion that proves that for the article embedding search, stay on this page instead of advancing.

Glossary: tool · Glossary: structured output · Cheatsheet: production ops signals

Previous · Next