Prerequisites and integration point
An embedding response can be valid JSON yet contain a vector your index cannot use. Check the vector at the adapter boundary before storing it or combining it with existing records. This Python 3.12 example accepts a parsed list and an application-configured dimension. It uses only math and built-in types. The response dictionary is a fixture representing the point after a transport has decoded a response.
The application supplies the expected dimension. Do not infer it independently from every response: that would allow a model or configuration change to mix incompatible vectors in one collection. Associate a real collection with its model configuration and rebuild or migrate it deliberately when the embedding space changes. A matching dimension alone does not prove that two models produce compatible coordinates.
Validate without coercing malformed input
The function requires a list of exactly the expected length. It accepts built-in integer and floating-point components, then converts them to floats. Booleans and numeric strings are rejected. This avoids turning an accidental true value into the coordinate 1.0 or accepting a response that has unexpectedly serialized all its numbers as text.
Each converted component must be finite. The norm is computed with math.hypot, then checked for zero and non-finite results because this boundary is intended for cosine-based use. A zero vector has no usable cosine direction. Very large integers can fail during conversion, so that failure is translated into the same ValueError family as other invalid vectors.
Snapshot semantics and edge cases
The result is a tuple containing new float values. The fixture changes its original list after validation and verifies that the accepted vector remains unchanged. This makes the boundary useful when response objects are reused or passed through other processing steps. It does not normalize the vector; downstream code must use the normalization policy expected by its index.
Large magnitude alone is not a reason to reject a vector. Three coordinates of 1e308 still have a finite norm here, and the test accepts them. However, downstream dot products can still overflow with such coordinates. If your index needs unit vectors, add and separately test normalization before calculating dot products. This example promises boundary checks, not universal numerical stability for every later operation.
Troubleshooting and validation scope
If dimension failures start after a deployment, inspect the configured model and requested output dimension before padding or truncating data. For non-finite failures, retain a safe record identifier and error category rather than dumping complete user text into logs. Do not replace NaN with zero without a documented domain policy.
The tests reject nine malformed vectors and three invalid dimension configurations. They also verify an accepted large vector and mutation isolation. The fixture does not exercise an HTTP client, a provider-specific response envelope, an actual model or a vector database. Add those integration tests separately while retaining these fast boundary checks.
Complete example
Save as embedding.py.
import math
def embedding(value, dimension):
if type(dimension) is not int or dimension <= 0:
raise ValueError("invalid dimension")
if type(value) is not list or len(value) != dimension:
raise ValueError("wrong vector shape")
result = []
for x in value:
if type(x) not in (int, float):
raise ValueError("non-numeric component")
try:
x = float(x)
except OverflowError as error:
raise ValueError("component too large") from error
if not math.isfinite(x):
raise ValueError("non-finite component")
result.append(x)
norm = math.hypot(*result)
if not math.isfinite(norm) or norm == 0:
raise ValueError("unusable cosine norm")
return tuple(result)
fixture = {"embedding": [0.3, 0.4, 0]}
vector = embedding(fixture["embedding"], 3)
fixture["embedding"][0] = 99
assert vector == (0.3, 0.4, 0.0)
bad = [[], [1, 2], [True, 1, 2], ["1", 2, 3], [0, 0, 0],
[float("nan"), 1, 2], [float("inf"), 1, 2], [10**400, 1, 2],
[[1], 2, 3], [1e308, 1e308, 1e308]]
# The last vector has a finite norm and is valid: do not reject magnitude alone.
assert len(embedding(bad.pop(), 3)) == 3
for value in bad:
try:
embedding(value, 3)
except ValueError:
pass
else:
raise AssertionError("invalid vector accepted")
for dim in (0, -1, True):
try:
embedding([1], dim)
except ValueError:
pass
else:
raise AssertionError("invalid dimension accepted")
print("accepted=(0.3, 0.4, 0.0); rejected=9; dimension_checks=3")
Run and expected output
python3 embedding.pyaccepted=(0.3, 0.4, 0.0); rejected=9; dimension_checks=3Primary references
Continue with Python tutorials and AI tutorials.