Sherlock text embedding models on CloudFerro Cloud
Text embedding models convert text into numerical vectors that represent semantic meaning. These vectors can then be used for similarity search, document retrieval, clustering, classification, recommendation systems, and retrieval-augmented generation workflows. Sherlock AI provides embedding models through an OpenAI-compatible API, so existing client libraries can be used by setting the Sherlock AI API key and base URL.
Endpoint
Send a POST request to the embeddings endpoint:
https://api-sherlock.cloudferro.com/openai/v1/embeddings
The request must include the Sherlock AI API key in the Authorization header. The selected embedding model is passed in the model field, and the text to embed is passed in the input field.
Available embedding models
Use one of the following model IDs when creating embeddings.
Model ID |
|---|
BAAI/bge-multilingual-gemma2 |
intfloat/e5-mistral-7b-instruct |
dunzhang/stella_en_1.5B_v5 |
sdadas/stella-pl-retrieval-8k |
Model IDs are case-sensitive. Copy the value exactly as shown in the table or as returned by the models endpoint.
Prerequisites
Before you start, make sure that you have access to a Sherlock AI project, that you have created and copied an API key, and that the key is stored in the SHERLOCK_API_KEY environment variable. For the Python example, you also need Python and the OpenAI client library installed.
Install the Python package with:
pip install openai
On Linux or macOS, store the API key with:
export SHERLOCK_API_KEY="paste-your-api-key-here"
On Windows PowerShell, use:
$env:SHERLOCK_API_KEY="paste-your-api-key-here"
Create embeddings with curl
The following curl example sends one text input to the embeddings endpoint. The API key is read from the SHERLOCK_API_KEY environment variable and passed as a bearer token.
curl https://api-sherlock.cloudferro.com/openai/v1/embeddings \
-H "Authorization: Bearer $SHERLOCK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "BAAI/bge-multilingual-gemma2",
"input": "Hello, world!"
}'
A successful response contains an embedding vector for the provided input text. The vector is an array of numbers and is usually stored in a vector database, search index, or application database together with the original text or document identifier.
The result:
Create embeddings with Python
The Python example uses the OpenAI client library and sends requests to Sherlock AI by setting the base_url value.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["SHERLOCK_API_KEY"],
base_url="https://api-sherlock.cloudferro.com/openai/v1",
)
response = client.embeddings.create(
model="BAAI/bge-multilingual-gemma2",
input="Hello, world!",
)
embedding = response.data[0].embedding
print("Text embedding:", embedding)
In real applications, you usually do not print the full vector. Instead, store it and use it later for similarity search, for example to find documents that are semantically close to a user query.
Embed more than one text
You can also send multiple text inputs in one request. This is useful when preparing a document collection for search or retrieval.
response = client.embeddings.create(
model="BAAI/bge-multilingual-gemma2",
input=[
"Sherlock AI provides OpenAI-compatible endpoints.",
"Embedding models convert text into numerical vectors.",
"Vector search can be used for document retrieval.",
],
)
for item in response.data:
print(item.index, item.embedding)
Keep the original text, document ID, source file name, or other metadata together with each vector. Without metadata, the vector alone is difficult to use in search results or retrieval workflows.
Use embeddings in applications
Embeddings are most often used as part of a larger workflow. A common pattern is to split documents into smaller chunks, create an embedding for each chunk, store the vectors in a vector database, and then embed the user query at search time. The application compares the query vector with stored vectors and returns the most similar chunks to the model or to the user.
For retrieval-augmented generation, send only the relevant retrieved text to a chat completion model. Do not send entire documents when a small number of matching chunks is enough. This reduces request size, improves latency, and keeps the prompt focused on the information needed for the answer.
Troubleshooting
If the request returns an authentication error, check that SHERLOCK_API_KEY is set in the same terminal session where you run curl or Python. If the model is rejected, copy the model ID again from the table or from the models endpoint and make sure that the selected model is available in your Sherlock AI project.
If Python cannot import the OpenAI library, install it in the same environment in which you run the script. On systems with several Python versions, use python3 -m pip install openai and run the script with the same python3 command.