Explanation

POST 
/explain

Better understand the source of a completion, specifically on how much each section of a prompt impacts each token of the completion.

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.

application/json

Bodyrequired

modelstringrequired
Name of the model to use.
hostingstringnullable
Determines in which datacenters the request may be processed. You can either set the parameter to "aleph-alpha" or omit it (defaulting to None).
Not setting this value, or setting it to None, gives us maximal flexibility in processing your request in our own datacenters and on servers hosted with other providers. Choose this option for maximal 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]
prompt 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
Text Prompt
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.
Multimodal
Array [
oneOf
Text
typestringrequired
Possible values: [text]
datastringrequired
controls object[]
Array [
startintegerrequired
Starting character index to apply the factor to.
lengthintegerrequired
The amount of characters to apply the factor to.
factornumberrequired
Factor to apply to the given token in the attention matrix.
• 0 <= factor < 1 => Suppress the given token
• factor == 1 => identity operation, no change to attention
• factor > 1 => Amplify the given token
token_overlapstring
What to do if a control partially overlaps with a text token.
If set to "partial", the factor will be adjusted proportionally with the amount of the token it overlaps. So a factor of 2.0 of a control that only covers 2 of 4 token characters, would be adjusted to 1.5. (It always moves closer to 1, since 1 is an identity operation for control factors.)
If set to "complete", the full factor will be applied as long as the control overlaps with the token at all.
Possible values: [partial, complete]
Default value: partial
]
Image
typestringrequired
Possible values: [image]
datastringrequired
An image send as part of a prompt to a model. The image is represented as base64.
Note: The models operate on square images. All non-square images are center-cropped before going to the model, so portions of the image may not be visible.
You can supply specific cropping parameters if you like, to choose a different area of the image than a center-crop. Or, you can always transform the image yourself to a square before sending it.
xinteger
x-coordinate of top left corner of cropping box in pixels
yinteger
y-coordinate of top left corner of cropping box in pixels
sizeinteger
Size of the cropping square in pixels
controls object[]
Array [
rect objectrequired
Bounding box in logical coordinates. From 0 to 1. With (0,0) being the upper left corner, and relative to the entire image.
Keep in mind, non-square images are center-cropped by default before going to the model. (You can specify a custom cropping if you want.). Since control coordinates are relative to the entire image, all or a portion of your control may be outside the "model visible area".
leftnumberrequired
x-coordinate of top left corner of the control bounding box. Must be a value between 0 and 1, where 0 is the left corner and 1 is the right corner.
topnumberrequired
y-coordinate of top left corner of the control bounding box Must be a value between 0 and 1, where 0 is the top pixel row and 1 is the bottom row.
widthnumberrequired
width of the control bounding box Must be a value between 0 and 1, where 1 means the full width of the image.
heightnumberrequired
height of the control bounding box Must be a value between 0 and 1, where 1 means the full height of the image.
factornumberrequired
Factor to apply to the given token in the attention matrix.
• 0 <= factor < 1 => Suppress the given token
• factor == 1 => identity operation, no change to attention
• factor > 1 => Amplify the given token
token_overlapstring
What to do if a control partially overlaps with an image token.
If set to "partial", the factor will be adjusted proportionally with the amount of the token it overlaps. So a factor of 2.0 of a control that only covers half of the image "tile", would be adjusted to 1.5. (It always moves closer to 1, since 1 is an identity operation for control factors.)
If set to "complete", the full factor will be applied as long as the control overlaps with the token at all.
Possible values: [partial, complete]
Default value: partial
]
Token Ids
typestringrequired
Possible values: [token_ids]
datainteger[]required
controls object[]
Array [
indexintegerrequired
Index of the token, relative to the list of tokens IDs in the current prompt item.
factornumberrequired
Factor to apply to the given token in the attention matrix.
• 0 <= factor < 1 => Suppress the given token
• factor == 1 => identity operation, no change to attention
• factor > 1 => Amplify the given token
]
]
targetstringnullablerequired
The completion string to be explained based on model probabilities.
control_factornumber
Factor to apply to the given token in the attention matrix.
• 0 <= factor < 1 => Suppress the given token
• factor == 1 => identity operation, no change to attention
• factor > 1 => Amplify the given token
Default value: 0.1
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
postprocessingstring
Optionally apply postprocessing to the difference in cross entropy scores for each token. "none": Apply no postprocessing. "absolute": Return the absolute value of each value. "square": Square each value
Possible values: [none, absolute, square]
Default value: none
normalizeboolean
Return normalized scores. Minimum score becomes 0 and maximum score becomes 1. Applied after any postprocessing
Default value: false
prompt_granularity object
typestring
At which granularity should the target be explained in terms of the prompt. If you choose, for example, "sentence" then we report the importance score of each sentence in the prompt towards generating the target output.
If you do not choose a granularity then we will try to find the granularity that brings you closest to around 30 explanations. For large documents, this would likely be sentences. For short prompts this might be individual words or even tokens.
If you choose a custom granularity then you must provide a custom delimiter. We then split your prompt by that delimiter. This might be helpful if you are using few-shot prompts that contain stop sequences.
For image prompt items, the granularities determine into how many tiles we divide the image for the explanation. "token" -> 12x12 "word" -> 6x6 "sentence" -> 3x3 "paragraph" -> 1
Possible values: [token, word, sentence, paragraph, custom]
delimiterstring
A delimiter string to split the prompt on if "custom" granularity is chosen.
target_granularitystring
How many explanations should be returned in the output.
"complete" -> Return one explanation for the entire target. Helpful in many cases to determine which parts of the prompt contribute overall to the given completion. "token" -> Return one explanation for each token in the target.
Possible values: [complete, token]
Default value: complete
control_token_overlapstring
What to do if a control partially overlaps with a text or image token.
If set to "partial", the factor will be adjusted proportionally with the amount of the token it overlaps. So a factor of 2.0 of a control that only covers 2 of 4 token characters, would be adjusted to 1.5. (It always moves closer to 1, since 1 is an identity operation for control factors.)
If set to "complete", the full factor will be applied as long as the control overlaps with the token at all.
Possible values: [partial, complete]
Default value: partial

Responses

200

OK

application/json

Schema

Schema

model_versionstring
explanations object[]
This array will contain one explanation object for each token in the target string.
Array [
targetstring
The string representation of the target token which is being explained
items object[]
Contains one item for each prompt item (in order), and the last item refers to the target.
Array [
oneOf
TokenIdsPromptItemImportance
typestring
Possible values: [token_ids]
scoresnumber[]
TargetItemImportance
typestring
Possible values: [target]
scores object[]
Array [
startinteger
lengthinteger
scorenumber
]
TextPromptItemImportance
typestring
Possible values: [text]
scores object[]
Array [
startinteger
lengthinteger
scorenumber
]
ImagePromptItemImportance
typestring
Possible values: [image]
scores object[]
Array [
rect object
topnumber
leftnumber
widthnumber
heightnumber
scorenumber
]
]
]

Example (auto)

{
  "model_version": "string",
  "explanations": [
    {
      "target": "string",
      "items": [
        {
          "type": "token_ids",
          "scores": [
            0
          ]
        },
        {
          "type": "target",
          "scores": [
            {
              "start": 0,
              "length": 0,
              "score": 0
            }
          ]
        },
        {
          "type": "text",
          "scores": [
            {
              "start": 0,
              "length": 0,
              "score": 0
            }
          ]
        },
        {
          "type": "image",
          "scores": [
            {
              "rect": {
                "top": 0,
                "left": 0,
                "width": 0,
                "height": 0
              },
              "score": 0
            }
          ]
        }
      ]
    }
  ]
}

Authorization: http

name: tokentype: httpscheme: bearerdescription: Can be generated in your [Aleph Alpha profile](https://app.aleph-alpha.com/profile)

• csharp
• curl
• dart
• go
• http
• java
• javascript
• kotlin
• c
• nodejs
• objective-c
• ocaml
• php
• powershell
• python
• r
• ruby
• rust
• shell
• swift

• HTTPCLIENT
• RESTSHARP

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://docs.aleph-alpha.com/explain");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Authorization", "Bearer <token>");
var content = new StringContent("{\n  \"model\": \"string\",\n  \"hosting\": \"aleph-alpha\",\n  \"prompt\": \"string\",\n  \"target\": \"string\",\n  \"control_factor\": 0.1,\n  \"contextual_control_threshold\": 0,\n  \"control_log_additive\": true,\n  \"postprocessing\": \"none\",\n  \"normalize\": false,\n  \"prompt_granularity\": {\n    \"type\": \"token\",\n    \"delimiter\": \"string\"\n  },\n  \"target_granularity\": \"complete\",\n  \"control_token_overlap\": \"partial\"\n}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Request Collapse all

Auth

Bearer Token

Parameters

nice — query

---truefalse

Body required

{
  "model": "string",
  "hosting": "aleph-alpha",
  "prompt": "string",
  "target": "string",
  "control_factor": 0.1,
  "contextual_control_threshold": 0,
  "control_log_additive": true,
  "postprocessing": "none",
  "normalize": false,
  "prompt_granularity": {
    "type": "token",
    "delimiter": "string"
  },
  "target_granularity": "complete",
  "control_token_overlap": "partial"
}