Migrate speaker embeddings to /v2/embedding with v3 sample migration

[beastoin]

Speaker sample migrations and live flows still generate v1 embeddings even though we now want the newer /v2/embedding model. We need a new migration stage (v3) that upgrades embeddings while reusing speech_samples_version as the single marker (no speaker_embedding_version) and removing all /v1/embedding usage. Related: #4253.

Current Behavior

• Embedding extraction posts to /v1/embedding everywhere.
• migrate_person_samples_v1_to_v2 regenerates embeddings using v1 and sets speech_samples_version = 2.
• No migration exists to upgrade embeddings only for already‑v2 samples.
• Lazy migration in speaker sample extraction only runs when speech_samples_version == 1.
• _add_sample_transaction sets speech_samples_version = 2 when transcripts are added, which doesn’t reflect embedding upgrades.
• Tests assume version 2 is the latest.

Expected Behavior

All embedding generation uses /v2/embedding, and speech_samples_version = 3 indicates samples/transcripts are migrated and embeddings are regenerated via /v2/embedding.

Affected Areas

File	Line	Description
backend/utils/stt/speaker_embedding.py	13-68	Hardcoded /v1/embedding endpoint.
backend/utils/speaker_sample_migration.py	34-143	v1→v2 migration and embedding regeneration logic.
backend/utils/speaker_identification.py	253-258	Lazy migration only for version 1.
backend/database/users.py	122-134	_add_sample_transaction sets version to 2.
backend/models/other.py	28	speech_samples_version default value.
backend/tests/unit/test_speaker_sample_migration.py	46-206	Assertions expect version 2.
backend/tests/unit/test_users_add_sample_transaction.py	83-114	Assertions expect version 2.

Solution

# Use /v2/embedding for all embedding extraction
def extract_embedding_from_bytes(...):
    response = requests.post(f"{api_url}/v2/embedding", ...)

# New migration stages using speech_samples_version only
async def migrate_person_samples_v1_to_v3(uid: str, person: dict) -> dict:
    person = await migrate_person_samples_v1_to_v2(uid, person)
    return await migrate_person_samples_v2_to_v3(uid, person)

async def migrate_person_samples_v2_to_v3(uid: str, person: dict) -> dict:
    # recompute embedding via /v2/embedding from latest sample
    # set speech_samples_version = 3

Files to Modify

• backend/utils/stt/speaker_embedding.py
• backend/utils/speaker_sample_migration.py
• backend/utils/speaker_identification.py
• backend/database/users.py
• backend/models/other.py
• backend/tests/unit/test_speaker_sample_migration.py
• backend/tests/unit/test_users_add_sample_transaction.py

Impact

Medium — migration logic and embedding compatibility; removes /v1/embedding usage.

---

by AI for @beastoin