Explanation
POSThttps://api.aleph-alpha.com/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
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
Body
required
- 0 <= factor < 1 => Suppress the given token
- factor == 1 => identity operation, no change to attention
- factor > 1 => Amplify the given token
Name of the model to use.
Possible values: [aleph-alpha
]
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.
prompt object required
The completion string to be explained based on model probabilities.
Default value: 0.1
Factor to apply to the given token in the attention matrix.
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: true
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
Possible values: [none
, absolute
, square
]
Default value: none
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
Default value: false
Return normalized scores. Minimum score becomes 0 and maximum score becomes 1. Applied after any postprocessing
prompt_granularity object
Possible values: [complete
, token
]
Default value: complete
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: [partial
, complete
]
Default value: partial
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.
Responses
- 200
OK
- application/json
- Schema
- Example (from schema)
Schema
explanations object[]
{
"model_version": "string",
"explanations": [
{
"target": "string",
"items": [
{},
{},
{},
{}
]
}
]
}
- curl
- python
- go
- nodejs
- ruby
- csharp
- php
- java
- powershell
- CURL
curl -L -X POST 'https://api.aleph-alpha.com/explain' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
"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"
}'