Skip to main content

Semantic Embeddings with instructions

POST 

https://api.aleph-alpha.com/instructable_embed

Embeds the input using an instruction and a specific model. Resulting vectors that can be used for downstream tasks (e.g. semantic similarity) and models (e.g. classifiers). To obtain a valid model, use GET /model-settings.

Request

Query Parameters

    nice boolean

    Setting this to True, will signal to the API that you intend to be nice to other users by de-prioritizing your request below concurrent ones.

Bodyrequired

    modelstring

    Name of the model to use. A model name refers to a model's architecture (number of parameters among others). The most recent version of the model is always used. The model output contains information as to the model version. To find out which models support semantic embeddings with instructions, please refer to the /model-settings endpoint.

    hostingHosting (string)nullable

    Optional parameter that specifies which datacenters may process the request. You can either set the parameter to "aleph-alpha" or omit it (defaulting to null).

    Not setting this value, or setting it to null, gives us maximal flexibility in processing your request in our own datacenters and on servers hosted with other providers. Choose this option for maximum availability.

    Setting it to "aleph-alpha" allows us to only process the request in our own datacenters. Choose this option for maximal data privacy.

    Possible values: [aleph-alpha, null]

    input objectrequired

    This field is used to send prompts to the model. A prompt can either be a text prompt or a multimodal prompt. A text prompt is a string of text. A multimodal prompt is an array of prompt items. It can be a combination of text, images, and token ID arrays.

    In the case of a multimodal prompt, the prompt items will be concatenated and a single prompt will be used for the model.

    Tokenization:

    • Token ID arrays are used as as-is.
    • Text prompt items are tokenized using the tokenizers specific to the model.
    • Each image is converted into 144 tokens.
    oneOf
    string

    The text to be completed. Unconditional completion can be started with an empty string (default). The prompt may contain a zero shot or few shot task.

    instructionstringrequired

    To further improve performance by steering the model, you can use instructions. Instructions can help the model understand nuances of your specific data and ultimately lead to embeddings that are more useful for your use-case. In this case, we aim to further increase the absolute difference between the cosine similarities. Instruction can also be the empty string.

    normalizeboolean

    Return normalized embeddings. This can be used to save on additional compute when applying a cosine similarity metric.

    Default value: false
    contextual_control_thresholdnumbernullable

    If set to null, attention control parameters only apply to those tokens that have explicitly been set in the request. If set to a non-null value, we apply the control parameters to similar tokens as well. Controls that have been applied to one token will then be applied to all other tokens that have at least the similarity score defined by this parameter. The similarity score is the cosine similarity of token embeddings.

    Default value: null
    control_log_additiveboolean

    true: apply controls on prompt items by adding the log(control_factor) to attention scores. false: apply controls on prompt items by (attention_scores - -attention_scores.min(-1)) * control_factor

    Default value: true

Responses

OK

Schema
    model_versionstring

    model name and version (if any) of the used model for inference

    embeddingfloat[]

    A list of floats that can be used to compare against other embeddings.

    num_tokens_prompt_totalinteger

    Number of tokens in the prompt.

    Tokenization:

    • Token ID arrays are used as as-is.
    • Text prompt items are tokenized using the tokenizers specific to the model.
    • Each image is converted into a fixed amount of tokens that depends on the chosen model.

Authorization: http

name: tokentype: httpscheme: bearerdescription: Can be generated in your [Aleph Alpha profile](https://app.aleph-alpha.com/profile)
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.aleph-alpha.com/instructable_embed");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Authorization", "Bearer <token>");
var content = new StringContent("{\n \"model\": \"pharia-1-embedding-4608-control\",\n \"input\": \"An apple a day keeps the doctor away.\",\n \"instruction\": \"Represent the user's question about rivers to find a relevant wikipedia paragraph\"\n}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
Request Collapse all
Base URL
https://api.aleph-alpha.com
Auth
Parameters
— query
Body required
{
  "model": "pharia-1-embedding-4608-control",
  "input": "An apple a day keeps the doctor away.",
  "instruction": "Represent the user's question about rivers to find a relevant wikipedia paragraph"
}
ResponseClear

Click the Send API Request button above and see the response here!