> ## Documentation Index
> Fetch the complete documentation index at: https://doc.lucidworks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Model predictions by use case
> This is an all-purpose prediction endpoint you can use by specifying a `USE_CASE` and `MODEL_ID`. Upon submission, the API responds with a unique `predictionId` and a `status`. The `predictionId` can be used later in the GET request to retrieve the results.
IMPORTANT: The available use cases are detailed in their own section in this specification.
## OpenAPI
````yaml /api-reference/saas/machine-learning-platform-async-prediction.json post /ai/async-prediction/{USE_CASE}/{MODEL_ID}
openapi: 3.0.1
info:
title: Lucidworks AI Async Prediction API
version: v0
description: >-
The Lucidworks AI Async Prediction API contains two requests:
* POST Request: This request is used to submit a prediction task for a
specific `useCase` and `modelId`. Upon submission, the API responds with the
following information:
* `predictionId` that is a unique UUID for the submitted prediction task, and can be used later to retrieve the results.
* `status` that indicates the current state of the prediction task.
* GET Request: This request is used to retrieve the results of a
previously-submitted prediction request. You must provide the unique
`predictionId` received from the POST request. The API then returns the
results of the prediction request associated with that `predictionId`.
The Use Case API returns a list of all supported models.
The `async-prediction` endpoints require an authentication token with scope
`machinelearning.predict`.
contact:
name: Lucidworks
url: https://lucidworks.com/
email: support@lucidworks.com
termsOfService: https://lucidworks.com/legal/developer-license-agreement/
license:
name: Lucidworks
url: https://lucidworks.com/legal/developer-license-agreement/
servers:
- url: https://APPLICATION_ID.applications.lucidworks.com
description: Production
security: []
tags:
- name: Create predictions
description: Submit prediction tasks to Lucidworks AI.
- name: Fetch predictions
description: Get the results of a prediction task from Lucidworks AI.
paths:
/ai/async-prediction/{USE_CASE}/{MODEL_ID}:
parameters:
- schema:
type: string
name: USE_CASE
in: path
required: true
description: >-
The name of the use case for the model. Use the Use Case API to get
the list of supported use cases.
example: ner
- schema:
type: string
name: MODEL_ID
in: path
required: true
description: The unique identifier for the model.
example: llama-3-8b-instruct
post:
tags:
- Create predictions
summary: Model predictions by use case
description: >-
This is an all-purpose prediction endpoint you can use by specifying a
`USE_CASE` and `MODEL_ID`. Upon submission, the API responds with a
unique `predictionId` and a `status`. The `predictionId` can be used
later in the GET request to retrieve the results.
IMPORTANT: The available use cases are detailed in their own section in
this specification.
operationId: post-ai-async-prediction-usecase-modelId
parameters:
- schema:
type: string
name: USE_CASE
in: path
required: true
description: >-
The name of the use case for the model. Use the Use Case API to get
the list of supported use cases.
example: ner
- in: header
name: Authorization
schema:
type: string
required: true
description: >-
Bearer token used for authentication. Format: `Authorization: Bearer
ACCESS_TOKEN`.
example: Bearer abc123def456
- schema:
type: string
in: header
name: Content-Type
description: application/json
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BasicGenericRequest'
examples:
Keyword extraction request:
value:
batch:
- text: >-
Joseph Robinette Biden Jr.is an American politician who
is the 46th and current president of the United States.
Ideologically a moderate member of the Democratic Party,
he previously served as the 47th vice president from
2009 to 2017 under President Barack Obama and
represented Delaware in the United States Senate from
1973 to 2009.Born in Scranton, Pennsylvania, Biden moved
with his family to Delaware in 1953. He studied at the
University of Delaware before earning his law degree
from Syracuse University. He was elected to the New
Castle County Council in 1970 and to the U.S. Senate in
1972. As a senator, Biden drafted and led the effort to
pass the Violent Crime Control and Law Enforcement Act
and the Violence Against Women Act. He also oversaw six
U.S. Supreme Court confirmation hearings, including the
contentious hearings for Robert Bork and Clarence
Thomas. Biden ran unsuccessfully for the Democratic
presidential nomination in 1988 and 2008. In 2008, Obama
chose Biden as his running mate, and Biden was a close
counselor to Obama during his two terms as vice
president. In the 2020 presidential election, Biden and
his running mate, Kamala Harris, defeated incumbents
Donald Trump and Mike Pence. Biden is the second
Catholic president in U.S. history (after John F.
Kennedy), and his politics have been widely described as
profoundly influenced by Catholic social teaching.
useCaseConfig:
maxKeywords: 100
NER request:
value:
batch:
- text: >-
Mahatma Gandhi, born on October 2, 1869, in Porbandar,
India, led a life that profoundly shaped the course of
history. Inspired by his principles of non-violence,
truth, and civil disobedience, Gandhi became a pivotal
figure in India's struggle for independence from British
rule. His journey began as a lawyer in South Africa,
where he experienced racial discrimination and
injustice, sparking his commitment to social justice.
Returning to India, he became the face of the nonviolent
resistance movement, employing methods like peaceful
protests, fasting, and marches. The iconic Salt March of
1930 exemplified his philosophy as thousands followed
him in the defiance of salt taxes imposed by the
British. Gandhi's ascetic lifestyle, clad in simple
attire and practicing self-sufficiency, endeared him to
the masses. Despite facing imprisonment multiple times,
he remained steadfast in his pursuit of India's freedom.
Tragically, Gandhi was assassinated on January 30, 1948,
but his legacy endures globally as a symbol of peace,
tolerance, and the transformative power of nonviolent
resistance
useCaseConfig:
entityTypeMap:
Location:
- India
- South Africa
Passthrough request:
value:
batch:
- text: who was the first president of the USA?
useCaseConfig:
useSystemPrompt: true
RAG request:
value:
batch:
- text: Why did I go to Germany?
documents:
- body: I'm off to Germany to go to the Oktoberfest!
source: http://example.com/112
title: Off to Germany!
date: '2022-01-31T19:31:34Z'
Standalone query rewriter request:
value:
batch:
- text: Is it a framework?
useCaseConfig:
memoryUuid: 27a887fe-3d7c-4ef0-9597-e2dfc054c20e
Summarization request:
value:
batch:
- text: >-
Nearly ten years had passed since the Dursleys had woken
up to find their nephew on the front step, but Privet
Drive had hardly changed at all. The sun rose on the
same tidy front gardens and lit up the brass number four
on the Dursleys' front door; it crept into their living
room, which was almost exactly the same as it had been
on the night when Mr. Dursley had seen that fateful news
report about the owls. Only the photographs on the
mantelpiece really showed how much time had passed. Ten
years ago, there had been lots of pictures of what
looked like a large pink beach ball wearing
different-colored bonnets - but Dudley Dursley was no
longer a baby, and now the photographs showed a large
blond boy riding his first bicycle, on a carousel at the
fair, playing a computer game with his father, being
hugged and kissed by his mother. The room held no sign
at all that another boy lived in the house, too.
useCaseConfig:
maxWords: 100
required: true
description: >-
Request information varies based on the use case in the request. See
the specific use case for valid information for that use case.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/POSTresponse'
examples: {}
4XX:
$ref: '#/components/responses/Error'
components:
schemas:
BasicGenericRequest:
title: BasicGenericRequest
type: object
description: ''
x-examples: {}
properties:
batch:
type: array
description: >-
The batch of key:value pairs used as inputs in the prediction. Up to
32 inputs per request are allowed.
maxItems: 32
items:
type: object
properties:
text:
type: string
description: The content the model analyzes.
example: The content the model analyzes.
modelConfig:
$ref: '#/components/schemas/ModelConfig'
POSTresponse:
title: POST response
type: object
description: >-
This is the response to the POST prediction request submitted for a
specific `useCase` and `modelId`.
properties:
predictionId:
type: string
format: uuid
description: >-
The universal unique identifier (UUID) returned in the POST request.
This UUID is required in the GET request to retrieve results.
status:
type: string
example: SUBMITTED
description: >-
The current status of the prediction. Allowed values are:
* SUBMITTED - The POST request was successful and the response has
returned the `predictionId` and `status` that is used by the GET
request.
* ERROR - An error was generated when the GET request was sent.
* READY - The results associated with the `predictionId` are
available and ready to be retrieved.
* RETRIEVED - The results associated with the `predictionId` are
returned successfully when the GET request was sent.
ModelConfig:
title: ModelConfig
type: object
description: >-
Provides fields and values that specify ranges for tokens. Fields used
for specific use cases and models are specified. The default values are
used if other values are not specified.
properties:
temperature:
type: number
format: float
example: 0.8
minimum: 0
maximum: 2
description: >-
A sampling temperature between 0 and 2. A higher sampling
temperature such as 0.8, results in more random (creative) output. A
lower value such as 0.2 results in more focused (conservative)
output. A lower value does not guarantee the model returns the same
response for the same input. We recommend staying at or below a
temperature of 1.0. Values above 1.0 might return nonsense unless
the topP value is lowered to be more deterministic.
topP:
type: number
format: float
example: 1
minimum: 1
maximum: 1
description: >-
A floating-point number that controls the cumulative probability of
the top tokens to consider. Required range is [0, 1]. Set topP to 1
to consider all tokens.
topK:
type: integer
example: -1
description: >-
An integer that controls the number of top tokens to consider. Set
topK to -1 to consider all tokens.
presencePenalty:
type: number
format: float
minimum: -2
maximum: 2
description: >-
A floating-point number that penalizes new tokens based on whether
they have already appeared in the text. Required range is [-2, 2]. A
value greater than zero (0) encourages the model to use new tokens.
A value less than zero (0) encourages the model to repeat existing
tokens. This is applicable for all OpenAI and Llama models.
example: 2
frequencyPenalty:
type: number
format: float
minimum: -2
maximum: 2
example: 1
description: >-
A floating-point number that penalizes new tokens based on their
frequency in the generated text. Required range is [-2, 2]. A value
greater than zero (0) encourages the model to use new tokens. A
value less than zero (0) encourages the model to repeat existing
tokens. This is applicable for all OpenAI and Llama models.
maxTokens:
type: integer
format: int32
example: 1
description: The maximum number of tokens to generate per output sequence.
apiKey:
type: string
description: >-
This optional parameter is only required when using the model for
prediction. You can find this value in your model's settings:
* **OpenAI**: Copy and paste the API key found in your
organization's settings. For more information, see OpenAI
Authentication API keys.
* **Azure OpenAI**: Copy and paste the API key found in your Azure
portal. See Authenticate
with API key.
* **Anthropic**: Copy and paste the API key found in your Anthropic
console or by using the Anthropic
API.
* **Google Vertex AI**: Copy and paste the base64-encoded service
account key JSON found in your Google
Cloud console. This service account key must have the Vertex
AI user role enabled. For more information, see generate
service account key.
example: API key specific to use case and model
azureDeployment:
type: string
description: >-
This optional parameter is the name of the deployed Azure OpenAI
model and is only required when a deployed Azure OpenAI model is
used for prediction.
example: DEPLOYMENT_NAME
azureEndpoint:
type: string
description: >-
This optional parameter is the URL endpoint of the deployed Azure
OpenAI model and is only required when a deployed Azure OpenAI model
is used for prediction.
example: https://azure.endpoint.com
googleProjectId:
type: string
example: '[GOOGLE_PROJECT_ID]'
description: >-
This parameter is optional, and is only required when a Google
Vertex AI model is used for prediction.
googleRegion:
type: string
description: >-
This parameter is optional, and is only required when a Google
Vertex AI model is used for prediction. A value of `global` routes
the query to any available region. Other possible region values are:
* us-central1
* us-west4
* northamerica-northeast1
* us-east4
* us-west1
* asia-northeast3
* asia-southeast1
* asia-northeast
example: '[GOOGLE_PROJECT_REGION_OF_MODEL_ACCESS]'
predictionId:
title: predictionId
type: string
description: >-
The universal unique identifier (UUID) returned in the POST request.
This UUID is required in the GET request to retrieve results.
format: uuid
example: fd110486-f168-47c0-a419-1518a4840589
status:
title: status
type: string
description: >-
The current status of the prediction. Allowed values are:
* `SUBMITTED` - The POST request was successful and the response has
returned the `predictionId` and `status` that is used by the GET
request.
* `READY` - The results associated with the `predictionId` are available
and ready to be retrieved.
* `ERROR` - An error was generated when the GET request was sent.
* `RETRIEVED` - The results associated with the `predictionId` are
returned successfully when the GET request was sent.
example: READY
responses:
Error:
description: >-
The error varies based on the issue encountered regarding the
`predictionId` or related information.
content:
application/json:
schema:
type: object
properties:
predictionId:
$ref: '#/components/schemas/predictionId'
status:
$ref: '#/components/schemas/status'
message:
type: string
description: >-
The error generated if the `predictionId` cannot be located or
the related information cannot be retrieved. For example,
"System prompt exceeded the maximum number of allowed input
tokens."
````