Pinecone: dimension and metric must match your embedding model, set once

Dimension and metric: get them right at creation, they are frozen

The rule

dimension must equal the number of floats your embedding model outputs. metric must suit how you compare them:

• cosine: normalized embeddings (most text models, e.g. OpenAI text-embedding-3). The common default.
• dotproduct: unnormalized embeddings, or sparse-only indexes.
• euclidean: when you genuinely need L2 distance.

Why agents get this wrong

The failure mode is creating the index first and choosing the embedding model later, or swapping models mid-project. text-embedding-3-small outputs 1536 dims; text-embedding-3-large outputs 3072; many open models output 768 or 1024. Upserting 768-dim vectors into a 1536-dim index fails every record with a dimension-mismatch error. There is no alter-index; you delete and recreate, then re-upsert everything.

Checklist before create_index

1. Decide the embedding model first. Print len(embedding) once and use that number.
2. Pick the metric from the list above, not from habit. If your vectors are L2-normalized, cosine and dotproduct agree; if they are not, they do not.
3. If you need sparse vectors (keyword signals), set vector_type appropriately at creation too.
4. Name the index after the model and dimension (e.g. docs-ada-1536) so a future agent can see the pairing without reading code.

If you already messed it up

Do not try to "fix" the vectors to fit (truncating or padding silently destroys recall). Create a new index with the right dimension, re-embed, re-upsert. For large indexes use the bulk import path rather than re-upserting one by one.