Embeddings Endpoint Testing Guide
This document provides manual testing steps and examples for the OpenAI-style embeddings endpoint.
Overview
The mock server provides an embeddings endpoint at /v1/embeddings that generates deterministic mock embeddings for development and testing purposes.
Quick Test Commands
1. Basic Single Input Test
curl -X POST http://localhost:8001/v1/embeddings \
-H "Content-Type: application/json" \
-d '{
"model": "text-embedding-ada-002",
"input": "Hello world"
}'Expected Response:
{
"object": "list",
"data": [
{
"object": "embedding",
"index": 0,
"embedding": [0.1234, -0.5678, 0.9012, ...]
}
],
"model": "text-embedding-ada-002",
"usage": {
"prompt_tokens": 2,
"total_tokens": 2
}
}2. Multiple Inputs Test
curl -X POST http://localhost:8001/v1/embeddings \
-H "Content-Type: application/json" \
-d '{
"model": "text-embedding-ada-002",
"input": ["First input", "Second input", "Third input"]
}'Expected Response:
{
"object": "list",
"data": [
{
"object": "embedding",
"index": 0,
"embedding": [0.1234, -0.5678, 0.9012, ...]
},
{
"object": "embedding",
"index": 1,
"embedding": [0.2345, -0.6789, 0.0123, ...]
},
{
"object": "embedding",
"index": 2,
"embedding": [0.3456, -0.7890, 0.1234, ...]
}
],
"model": "text-embedding-ada-002",
"usage": {
"prompt_tokens": 6,
"total_tokens": 6
}
}3. Custom Dimensions Test
curl -X POST http://localhost:8001/v1/embeddings \
-H "Content-Type: application/json" \
-d '{
"model": "text-embedding-ada-002",
"input": "Test custom dimensions",
"dimensions": 256
}'Expected Response:
- Embedding array should have 256 dimensions instead of default 128
4. GET Request Test
curl -X GET "http://localhost:8001/v1/embeddings?model=text-embedding-3-small&input=GET%20test&dimensions=64"Expected Response:
- Same format as POST requests
- Uses query parameters instead of JSON body
Verification Steps
1. Verify Response Structure
Check that the response contains:
- ✅
object: "list" - ✅
dataarray with correct length - ✅ Each data item has
object: "embedding",index, andembeddingarray - ✅
modelfield matches request - ✅
usageobject withprompt_tokensandtotal_tokens
2. Verify Determinism
Test 1: Same Input, Same Model
# First request
curl -X POST http://localhost:8001/v1/embeddings \
-H "Content-Type: application/json" \
-d '{"model": "text-embedding-ada-002", "input": "determinism test"}' > response1.json
# Second request
curl -X POST http://localhost:8001/v1/embeddings \
-H "Content-Type: application/json" \
-d '{"model": "text-embedding-ada-002", "input": "determinism test"}' > response2.json
# Compare (should be identical)
diff response1.json response2.jsonExpected: No differences between files
Test 2: Different Inputs
# Request with different input
curl -X POST http://localhost:8001/v1/embeddings \
-H "Content-Type: application/json" \
-d '{"model": "text-embedding-ada-002", "input": "different input"}' > response3.json
# Compare (should be different)
diff response1.json response3.jsonExpected: Files should be different
Test 3: Different Models, Same Input
# Request with different model
curl -X POST http://localhost:8001/v1/embeddings \
-H "Content-Type: application/json" \
-d '{"model": "text-embedding-3-small", "input": "determinism test"}' > response4.json
# Compare (should be different)
diff response1.json response4.jsonExpected: Files should be different
3. Verify Error Handling
Invalid Request (Missing Model):
curl -X POST http://localhost:8001/v1/embeddings \
-H "Content-Type: application/json" \
-d '{"input": "missing model"}'Expected Response:
- Status: 400
- Error message about invalid request format
Invalid Request (Missing Input):
curl -X POST http://localhost:8001/v1/embeddings \
-H "Content-Type: application/json" \
-d '{"model": "text-embedding-ada-002"}'Expected Response:
- Status: 400
- Error message about invalid request format
4. Verify Configuration
Check UI Dashboard:
- Visit
http://localhost:8001 - Verify "Embeddings Status" shows "ENABLED" or "DISABLED"
- Verify "Embedding Dimensions" shows the configured value
- Verify "/v1/embeddings" appears in API links when enabled
Test Environment Variables:
# Disable embeddings
echo "ENABLE_EMBEDDINGS_MOCK=false" > .env.test
# Restart server and verify endpoint returns 404
# Change dimensions
echo "EMBEDDING_DIMENSION=64" > .env.test
# Restart server and verify embeddings have 64 dimensionsIntegration Testing
With OpenAI Client Libraries
JavaScript/Node.js:
import { OpenAI } from 'openai';
const openai = new OpenAI({
baseURL: 'http://localhost:8001/v1',
apiKey: 'sk-mock-key' // Mock key for development
});
const response = await openai.embeddings.create({
model: 'text-embedding-ada-002',
input: 'Your text here'
});
console.log(response.data[0].embedding); // Should be array of numbersPython:
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8001/v1",
api_key="sk-mock-key"
)
response = client.embeddings.create(
model="text-embedding-ada-002",
input="Your text here"
)
print(response.data[0].embedding) # Should be array of numbersWith LangChain
import { OpenAIEmbeddings } from '@langchain/openai';
const embeddings = new OpenAIEmbeddings({
openAIApiKey: 'sk-mock-key',
modelName: 'text-embedding-ada-002',
configuration: {
baseURL: 'http://localhost:8001/v1',
},
});
const result = await embeddings.embedQuery("Hello world");
console.log(result); // Should be array of numbersPerformance and Limits
- Default Dimensions: 128 (configurable via
EMBEDDING_DIMENSION) - Custom Dimensions: Supported up to reasonable limits (tested up to 2048)
- Multiple Inputs: Supports arrays, tested up to 10 inputs
- Response Time: Fast (mock data, no real computation)
- Determinism: Guaranteed for same (model, input) combination
Troubleshooting
Common Issues
404 Error:
- Check
ENABLE_EMBEDDINGS_MOCK=truein environment - Restart server after changing environment variables
- Check
400 Error:
- Verify request includes both
modelandinputfields - Check JSON syntax and content-type header
- Verify request includes both
Wrong Dimensions:
- Check
EMBEDDING_DIMENSIONenvironment variable - Verify
dimensionsparameter in request
- Check
Non-deterministic Results:
- Ensure same model and input values
- Check for hidden characters or whitespace differences
Debug Commands
# Check server status
curl http://localhost:8001/ping
# Check UI metadata (includes embeddings status)
curl http://localhost:8001/ui-meta
# Check logs for detailed request information
curl http://localhost:8001/ui-request-logAutomated Tests
The project includes comprehensive automated tests:
- Unit Tests:
npm run test:unit -- src/tests/utilities/response-helpers-embeddings.test.ts - E2E Tests:
npm run test:embeddings - All Tests:
npm run test:e2e(includes embeddings tests)
Run these commands to verify the implementation works correctly after making changes.