Skip to content

Commit 5cf8555

Browse files
prmerger-automator[bot]prmerger-automator[bot]
authored
Merge pull request #262593 from aahill/proj-weds-api
updating Azure OpenAI API reference
2 parents 93354dc + c417aea commit 5cf8555

File tree

1 file changed

+282
-7
lines changed

1 file changed

+282
-7
lines changed

‎articles/ai-services/openai/reference.md

Lines changed: 282 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -358,10 +358,10 @@ POST {your-resource-name}/openai/deployments/{deployment-id}/extensions/chat/com
358358
- `2023-06-01-preview` [Swagger spec](https://github.com/Azure/azure-rest-api-specs/blob/main/specification/cognitiveservices/data-plane/AzureOpenAI/inference/preview/2023-06-01-preview/inference.json)
359359
- `2023-07-01-preview` [Swagger spec](https://github.com/Azure/azure-rest-api-specs/blob/main/specification/cognitiveservices/data-plane/AzureOpenAI/inference/preview/2023-07-01-preview/inference.json)
360360
- `2023-08-01-preview` [Swagger spec](https://github.com/Azure/azure-rest-api-specs/blob/main/specification/cognitiveservices/data-plane/AzureOpenAI/inference/preview/2023-08-01-preview/inference.json)
361-
361+
- `2023-12-01-preview` [Swagger spec](https://github.com/Azure/azure-rest-api-specs/blob/main/specification/cognitiveservices/data-plane/AzureOpenAI/inference/preview/2023-12-01-preview/inference.json)
362362
#### Example request
363363

364-
You can make requests using [Azure AI Search](./concepts/use-your-data.md?tabs=ai-search#ingesting-your-data) and [Azure Cosmos DB for MongoDB vCore](./concepts/use-your-data.md?tabs=mongo-db#ingesting-your-data).
364+
You can make requests using [Azure AI Search](./concepts/use-your-data.md?tabs=ai-search#ingesting-your-data), [Azure Cosmos DB for MongoDB vCore](./concepts/use-your-data.md?tabs=mongo-db#ingesting-your-data), [Azure Machine learning](/azure/machine-learning/overview-what-is-azure-machine-learning), [Pinecone](https://www.pinecone.io/), and [Elasticsearch](https://www.elastic.co/).
365365

366366
##### Azure AI Search
367367

@@ -441,6 +441,123 @@ curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/exten
441441
'
442442
```
443443

444+
##### Elasticsearch
445+
446+
```console
447+
curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \
448+
-H "Content-Type: application/json" \
449+
-H "api-key: YOUR_API_KEY" \
450+
-d \
451+
{
452+
"messages": [
453+
{
454+
"role": "system",
455+
"content": "you are a helpful assistant that talks like a pirate"
456+
},
457+
{
458+
"role": "user",
459+
"content": "can you tell me how to care for a parrot?"
460+
}
461+
],
462+
"dataSources": [
463+
{
464+
"type": "Elasticsearch",
465+
"parameters": {
466+
"endpoint": "{search endpoint}",
467+
"indexName": "{index name}",
468+
"authentication": {
469+
"type": "KeyAndKeyId",
470+
"key": "{key}",
471+
"keyId": "{key id}"
472+
}
473+
}
474+
}
475+
]
476+
}
477+
```
478+
479+
##### Azure Machine Learning
480+
481+
```console
482+
curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \
483+
-H "Content-Type: application/json" \
484+
-H "api-key: YOUR_API_KEY" \
485+
-d \
486+
'
487+
{
488+
"messages": [
489+
{
490+
"role": "system",
491+
"content": "you are a helpful assistant that talks like a pirate"
492+
},
493+
{
494+
"role": "user",
495+
"content": "can you tell me how to care for a parrot?"
496+
}
497+
],
498+
"dataSources": [
499+
{
500+
"type": "AzureMLIndex",
501+
"parameters": {
502+
"projectResourceId": "/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.MachineLearningServices/workspaces/{workspace-id}",
503+
"name": "my-project",
504+
"version": "5"
505+
}
506+
}
507+
]
508+
}
509+
'
510+
```
511+
512+
##### Pinecone
513+
514+
```console
515+
curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \
516+
-H "Content-Type: application/json" \
517+
-H "api-key: YOUR_API_KEY" \
518+
-d \
519+
'
520+
{
521+
"messages": [
522+
{
523+
"role": "system",
524+
"content": "you are a helpful assistant that talks like a pirate"
525+
},
526+
{
527+
"role": "user",
528+
"content": "can you tell me how to care for a parrot?"
529+
}
530+
],
531+
"dataSources": [
532+
{
533+
"type": "Pinecone",
534+
"parameters": {
535+
"authentication": {
536+
"type": "APIKey",
537+
"apiKey": "{api key}"
538+
},
539+
"environment": "{environment name}",
540+
"indexName": "{index name}",
541+
"embeddingDependency": {
542+
"type": "DeploymentName",
543+
"deploymentName": "{embedding deployment name}"
544+
},
545+
"fieldsMapping": {
546+
"titleField": "title",
547+
"urlField": "url",
548+
"filepathField": "filepath",
549+
"contentFields": [
550+
"content"
551+
],
552+
"contentFieldsSeparator": "\n"
553+
}
554+
}
555+
}
556+
]
557+
}
558+
'
559+
```
560+
444561
#### Example response
445562

446563
```json
@@ -469,6 +586,8 @@ curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/exten
469586
}
470587
```
471588

589+
590+
472591
| Parameters | Type | Required? | Default | Description |
473592
|--|--|--|--|--|
474593
| `messages` | array | Required | null | The messages to generate chat completions for, in the chat format. |
@@ -484,7 +603,7 @@ The following parameters can be used inside of the `parameters` field inside of
484603

485604
| Parameters | Type | Required? | Default | Description |
486605
|--|--|--|--|--|
487-
| `type` | string | Required | null | The data source to be used for the Azure OpenAI on your data feature. For Azure AI Search the value is `AzureCognitiveSearch`. For Azure Cosmos DB for MongoDB vCore, the value is `AzureCosmosDB`. |
606+
| `type` | string | Required | null | The data source to be used for the Azure OpenAI on your data feature. For Azure AI Search the value is `AzureCognitiveSearch`. For Azure Cosmos DB for MongoDB vCore, the value is `AzureCosmosDB`. For Elasticsearch the value is `Elasticsearch`. For Azure Machine Learning, the value is `AzureMLIndex`. For Pinecone, the value is `Pinecone`. |
488607
| `indexName` | string | Required | null | The search index to be used. |
489608
| `inScope` | boolean | Optional | true | If set, this value will limit responses specific to the grounding data content. |
490609
| `topNDocuments` | number | Optional | 5 | Specifies the number of top-scoring documents from your data index used to generate responses. You might want to increase the value when you have short documents or want to provide more context. This is the *retrieved documents* parameter in Azure OpenAI studio. |
@@ -497,7 +616,9 @@ The following parameters can be used inside of the `parameters` field inside of
497616
| `strictness` | number | Optional | 3 | Sets the threshold to categorize documents as relevant to your queries. Raising the value means a higher threshold for relevance and filters out more less-relevant documents for responses. Setting this value too high might cause the model to fail to generate responses due to limited available documents. |
498617

499618

500-
**The following parameters are used for Azure AI Search**
619+
### Azure AI Search parameters
620+
621+
The following parameters are used for Azure AI Search.
501622

502623
| Parameters | Type | Required? | Default | Description |
503624
|--|--|--|--|--|
@@ -506,6 +627,20 @@ The following parameters can be used inside of the `parameters` field inside of
506627
| `queryType` | string | Optional | simple | Indicates which query option will be used for Azure AI Search. Available types: `simple`, `semantic`, `vector`, `vectorSimpleHybrid`, `vectorSemanticHybrid`. |
507628
| `fieldsMapping` | dictionary | Optional for Azure AI Search. | null | defines which [fields](./concepts/use-your-data.md?tabs=ai-search#index-field-mapping) you want to map when you add your data source. |
508629

630+
The following parameters are used inside of the `authentication` field, which enables you to use Azure OpenAI [without public network access](./how-to/use-your-data-securely.md).
631+
632+
| Parameters | Type | Required? | Default | Description |
633+
|--|--|--|--|--|
634+
| `type` | string | Required | null | The authentication type. |
635+
| `managedIdentityResourceId` | string | Required | null | The resource ID of the user-assigned managed identity to use for authentication. |
636+
637+
```json
638+
"authentication": {
639+
"type": "UserAssignedManagedIdentity",
640+
"managedIdentityResourceId": "/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{resource-name}"
641+
},
642+
```
643+
509644
The following parameters are used inside of the `fieldsMapping` field.
510645

511646
| Parameters | Type | Required? | Default | Description |
@@ -514,7 +649,7 @@ The following parameters are used inside of the `fieldsMapping` field.
514649
| `urlField` | string | Optional | null | The field in your index that contains the original URL of each document. |
515650
| `filepathField` | string | Optional | null | The field in your index that contains the original file name of each document. |
516651
| `contentFields` | dictionary | Optional | null | The fields in your index that contain the main text content of each document. |
517-
| `contentFieldsSeparator` | string | Optional | null | The separator for the your content fields. Use `\n` by default. |
652+
| `contentFieldsSeparator` | string | Optional | null | The separator for the content fields. Use `\n` by default. |
518653

519654
```json
520655
"fieldsMapping": {
@@ -528,7 +663,23 @@ The following parameters are used inside of the `fieldsMapping` field.
528663
}
529664
```
530665

531-
**The following parameters are used for Azure Cosmos DB for MongoDB vCore**
666+
The following parameters are used inside of the optional `embeddingDependency` parameter, which contains details of a vectorization source that is based on an internal embeddings model deployment name in the same Azure OpenAI resource.
667+
668+
| Parameters | Type | Required? | Default | Description |
669+
|--|--|--|--|--|
670+
| `deploymentName` | string | Optional | null | The type of vectorization source to use. |
671+
| `type` | string | Optional | null | The embedding model deployment name, located within the same Azure OpenAI resource. This enables you to use vector search without an Azure OpenAI API key and without Azure OpenAI public network access. |
672+
673+
```json
674+
"embeddingDependency": {
675+
"type": "DeploymentName",
676+
"deploymentName": "{embedding deployment name}"
677+
},
678+
```
679+
680+
### Azure CosmosDB for MongoDB vCore parameters
681+
682+
The following parameters are used for Azure Cosmos DB for MongoDB vCore.
532683

533684
| Parameters | Type | Required? | Default | Description |
534685
|--|--|--|--|--|
@@ -538,7 +689,131 @@ The following parameters are used inside of the `fieldsMapping` field.
538689
| `containerName` | string | Required | null | Azure Cosmos DB for MongoDB vCore only. The Azure Cosmos Mongo vCore container name in the database. |
539690
| `type` (found inside of`embeddingDependencyType`) | string | Required | null | Indicates the embedding model dependency. |
540691
| `deploymentName` (found inside of`embeddingDependencyType`) | string | Required | null | The embedding model deployment name. |
541-
| `fieldsMapping` | dictionary | Required for Azure Cosmos DB for MongoDB vCore. | null | Index data column mapping. When using Azure Cosmos DB for MongoDB vCore, the value `vectorFields` is required, which indicates the fields that store vectors. |
692+
| `fieldsMapping` | dictionary | Required for Azure Cosmos DB for MongoDB vCore. | null | Index data column mapping. When you use Azure Cosmos DB for MongoDB vCore, the value `vectorFields` is required, which indicates the fields that store vectors. |
693+
694+
The following parameters are used inside of the optional `embeddingDependency` parameter, which contains details of a vectorization source that is based on an internal embeddings model deployment name in the same Azure OpenAI resource.
695+
696+
| Parameters | Type | Required? | Default | Description |
697+
|--|--|--|--|--|
698+
| `deploymentName` | string | Optional | null | The type of vectorization source to use. |
699+
| `type` | string | Optional | null | The embedding model deployment name, located within the same Azure OpenAI resource. This enables you to use vector search without an Azure OpenAI API key and without Azure OpenAI public network access. |
700+
701+
```json
702+
"embeddingDependency": {
703+
"type": "DeploymentName",
704+
"deploymentName": "{embedding deployment name}"
705+
},
706+
```
707+
708+
### Elasticsearch parameters
709+
710+
The following parameters are used for Elasticsearch.
711+
712+
| Parameters | Type | Required? | Default | Description |
713+
|--|--|--|--|--|
714+
| `endpoint` | string | Required | null | The endpoint for connecting to Elasticsearch. |
715+
| `indexName` | string | Required | null | The name of the Elasticsearch index. |
716+
| `type` (found inside of `authentication`) | string | Required | null | The authentication to be used. For Elasticsearch, the value is `KeyAndKeyId`. |
717+
| `key` (found inside of `authentication`) | string | Required | null | The key used to connect to Elasticsearch. |
718+
| `keyId` (found inside of `authentication`) | string | Required | null | The key ID to be used. For Elasticsearch. |
719+
720+
The following parameters are used inside of the `fieldsMapping` field.
721+
722+
| Parameters | Type | Required? | Default | Description |
723+
|--|--|--|--|--|
724+
| `titleField` | string | Optional | null | The field in your index that contains the original title of each document. |
725+
| `urlField` | string | Optional | null | The field in your index that contains the original URL of each document. |
726+
| `filepathField` | string | Optional | null | The field in your index that contains the original file name of each document. |
727+
| `contentFields` | dictionary | Optional | null | The fields in your index that contain the main text content of each document. |
728+
| `contentFieldsSeparator` | string | Optional | null | The separator for the content fields. Use `\n` by default. |
729+
| `vectorFields` | dictionary | Optional | null | The names of fields that represent vector data |
730+
731+
```json
732+
"fieldsMapping": {
733+
"titleField": "myTitleField",
734+
"urlField": "myUrlField",
735+
"filepathField": "myFilePathField",
736+
"contentFields": [
737+
"myContentField"
738+
],
739+
"contentFieldsSeparator": "\n",
740+
"vectorFields": [
741+
"myVectorField"
742+
]
743+
}
744+
```
745+
746+
The following parameters are used inside of the optional `embeddingDependency` parameter, which contains details of a vectorization source that is based on an internal embeddings model deployment name in the same Azure OpenAI resource.
747+
748+
| Parameters | Type | Required? | Default | Description |
749+
|--|--|--|--|--|
750+
| `deploymentName` | string | Optional | null | The type of vectorization source to use. |
751+
| `type` | string | Optional | null | The embedding model deployment name, located within the same Azure OpenAI resource. This enables you to use vector search without an Azure OpenAI API key and without Azure OpenAI public network access. |
752+
753+
```json
754+
"embeddingDependency": {
755+
"type": "DeploymentName",
756+
"deploymentName": "{embedding deployment name}"
757+
},
758+
```
759+
760+
### Azure Machine Learning parameters
761+
762+
The following parameters are used for Azure Machine Learning.
763+
764+
| Parameters | Type | Required? | Default | Description |
765+
|--|--|--|--|--|
766+
| `projectResourceId` | string | Required | null | The project resource ID. |
767+
| `name` | string | Required | null | The name of the Azure Machine Learning project name. |
768+
| `version` (found inside of `authentication`) | string | Required | null | The version of the Azure Machine Learning vector index. |
769+
770+
The following parameters are used inside of the optional `embeddingDependency` parameter, which contains details of a vectorization source that is based on an internal embeddings model deployment name in the same Azure OpenAI resource.
771+
772+
| Parameters | Type | Required? | Default | Description |
773+
|--|--|--|--|--|
774+
| `deploymentName` | string | Optional | null | The type of vectorization source to use. |
775+
| `type` | string | Optional | null | The embedding model deployment name, located within the same Azure OpenAI resource. This enables you to use vector search without an Azure OpenAI API key and without Azure OpenAI public network access. |
776+
777+
```json
778+
"embeddingDependency": {
779+
"type": "DeploymentName",
780+
"deploymentName": "{embedding deployment name}"
781+
},
782+
```
783+
784+
### Pinecone parameters
785+
786+
The following parameters are used for Pinecone.
787+
788+
| Parameters | Type | Required? | Default | Description |
789+
|--|--|--|--|--|
790+
| `type` (found inside of `authentication`) | string | Required | null | The authentication to be used. For Pinecone, the value is `APIKey`. |
791+
| `apiKey` (found inside of `authentication`) | string | Required | null | The API key for Pinecone. |
792+
| `environment` | string | Required | null | The name of the Pinecone environment. |
793+
| `indexName` | string | Required | null | The name of the Pinecone index. |
794+
| `embeddingDependency` | string | Required | null | The embedding dependency for vector search. |
795+
| `type` (found inside of `embeddingDependency`) | string | Required | null | The type of dependency. For Pinecone the value is `DeploymentName`. |
796+
| `deploymentName` (found inside of `embeddingDependency`) | string | Required | null | The name of the deployment. |
797+
| `titleField` (found inside of `fieldsMapping`) | string | Required | null | The name of the index field to use as a title. |
798+
| `urlField` (found inside of `fieldsMapping`) | string | Required | null | The name of the index field to use as a URL. |
799+
| `filepathField` (found inside of `fieldsMapping`) | string | Required | null | The name of the index field to use as a file path. |
800+
| `contentFields` (found inside of `fieldsMapping`) | string | Required | null | The name of the index fields that should be treated as content. |
801+
| `vectorFields` | dictionary | Optional | null | The names of fields that represent vector data |
802+
| `contentFieldsSeparator` (found inside of `fieldsMapping`) | string | Required | null | The separator for the your content fields. Use `\n` by default. |
803+
804+
The following parameters are used inside of the optional `embeddingDependency` parameter, which contains details of a vectorization source that is based on an internal embeddings model deployment name in the same Azure OpenAI resource.
805+
806+
| Parameters | Type | Required? | Default | Description |
807+
|--|--|--|--|--|
808+
| `deploymentName` | string | Optional | null | The type of vectorization source to use. |
809+
| `type` | string | Optional | null | The embedding model deployment name, located within the same Azure OpenAI resource. This enables you to use vector search without an Azure OpenAI API key and without Azure OpenAI public network access. |
810+
811+
```json
812+
"embeddingDependency": {
813+
"type": "DeploymentName",
814+
"deploymentName": "{embedding deployment name}"
815+
},
816+
```
542817

543818
### Start an ingestion job
544819

0 commit comments

Comments
 (0)