資料來源 - Elasticsearch (預覽)

發行項
10/16/2024

使用 Azure OpenAI On Your Data 時，Elasticsearch 的可設定選項。 API 第 2024-02-15-preview 版支援此資料來源。

名稱	類型	必要	描述
`parameters`	參數	True	設定 Elasticsearch 時要使用的參數。
`type`	字串	True	必須是 `elasticsearch`。

參數

姓名	類型	必要	描述
`endpoint`	string	True	Elasticsearch 資源所要使用的絕對端點路徑。
`index_name`	字串	True	在參考的 Elasticsearch 中要使用的索引名稱。
`authentication`	KeyAndKeyIdAuthenticationOptions、EncodedApiKeyAuthenticationOptions 其中一個	True	存取已定義資料來源時要使用的驗證方法。
`embedding_dependency`	One of DeploymentNameVectorizationSource、EndpointVectorizationSource、ModelIdVectorizationSource 其中一個	False	向量搜尋的內嵌相依性。當 `query_type` 為 `vector` 時為必要。
`fields_mapping`	FieldsMappingOptions	False	與搜尋索引互動時要使用的自訂欄位對應行為。
`in_scope`	boolean	False	查詢是否應限制為使用已編製索引的資料。預設值為 `True`。
`query_type`	QueryType	False	要搭配 Elasticsearch 使用的查詢類型。預設為 `simple`
`role_information`	字串	False	提供模型關於其行為方式的指示，以及產生回應時應該參考的任何內容。您可以描述助理的特質，並對其告知如何格式化回應。
`strictness`	整數	False	已設定的搜尋相關性篩選嚴格度。嚴格度越高，精確度就越高，但答案的召回率越低。預設值為 `3`。
`top_n_documents`	整數	False	要為設定的查詢顯示的已設定文件數目上限。預設值為 `5`。

金鑰和金鑰識別碼驗證選項

Azure OpenAI On Your Data 在使用 API 金鑰時的驗證選項。

名稱	類型	必要	描述
`key`	string	True	要用於驗證的 Elasticsearch 金鑰。
`key_id`	字串	True	要用於驗證的 Elasticsearch 金鑰識別碼。
`type`	字串	True	必須是 `key_and_key_id`。

編碼的 API 金鑰驗證選項

Azure OpenAI On Your Data 在使用 Elasticsearch 編碼 API 金鑰時的驗證選項。

名稱	類型	必要	描述
`encoded_api_key`	string	True	要用於驗證的 Elasticsearch 編碼 API 金鑰。
`type`	字串	True	必須是 `encoded_api_key`。

部署名稱向量化來源

套用向量搜尋時，Azure OpenAI On Your Data 所使用的向量化來源詳細資料。此向量化來源是以相同 Azure OpenAI 資源中的內部內嵌模型部署名稱為基礎。此向量化來源可讓您在沒有 Azure OpenAI API 金鑰的情況下使用向量搜尋，而不需要 Azure OpenAI 公用網路存取。

名稱	類型	必要	描述
`deployment_name`	string	True	相同 Azure OpenAI 資源內的內嵌模型部署名稱。
`type`	字串	True	必須是 `deployment_name`。

端點向量化來源

套用向量搜尋時，Azure OpenAI On Your Data 所使用的向量化來源詳細資料。此向量化來源是以 Azure OpenAI 內嵌 API 端點為基礎。

名稱	類型	必要	描述
`endpoint`	string	True	指定應從中擷取內嵌的資源端點 URL。其格式應為 `https://{YOUR_RESOURCE_NAME}.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/embeddings`。不允許 api-version 查詢參數。
`authentication`	ApiKeyAuthenticationOptions	True	指定從指定端點擷取內嵌時要使用的驗證選項。
`type`	字串	True	必須是 `endpoint`。

模型識別碼向量化來源

套用向量搜尋時，Azure OpenAI On Your Data 所使用的向量化來源詳細資料。此向量化來源是以 Elasticsearch 模型識別碼為基礎。

名稱	類型	必要	描述
`model_id`	string	True	指定要用於向量化的模型識別碼。此模型識別碼必須在 Elasticsearch 中定義。
`type`	字串	True	必須是 `model_id`。

API 金鑰驗證選項

Azure OpenAI On Your Data 在使用 API 金鑰時的驗證選項。

名稱	類型	必要	描述
`key`	string	True	要用於驗證的 API 金鑰。
`type`	字串	True	必須是 `api_key`。

欄位對應選項

選擇性設定，可控制使用已設定的 Elasticsearch 資源時處理欄位的方式。

名稱	類型	必要	描述
`content_fields`	string[]	False	應視為內容的索引欄位名稱。
`vector_fields`	string[]	False	代表向量資料的欄位名稱。
`content_fields_separator`	字串	False	內容欄位應使用的分隔符號模式。預設值為 `\n`。
`filepath_field`	字串	False	要用作檔案路徑的索引欄位名稱。
`title_field`	字串	False	要用作標題的索引欄位名稱。
`url_field`	字串	False	要用作 URL 的索引欄位名稱。

查詢類型

搭配 Azure OpenAI On Your Data 使用時所應執行的 Elasticsearch 擷取查詢類型。

列舉值	描述
`simple`	代表預設的簡單查詢剖析器。
`vector`	代表對計算資料的向量搜尋。

範例

先決條件：

設定從使用者到 Azure OpenAI 資源的角色指派。必要角色：Cognitive Services OpenAI User。
安裝 Az CLI，然後執行 az login。
定義下列環境變數：AzureOpenAIEndpoint、ChatCompletionsDeploymentName、SearchEndpoint、IndexName、Key、KeyId。

export AzureOpenAIEndpoint=https://example.openai.azure.com/
export ChatCompletionsDeploymentName=turbo
export SearchEndpoint='https://example.eastus.azurecontainer.io'
export IndexName=testindex
export Key='***'
export KeyId='***'

Python 1.x
REST

安裝最新的 pip 套件 openai、azure-identity。

import os
from openai import AzureOpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

endpoint = os.environ.get("AzureOpenAIEndpoint")
deployment = os.environ.get("ChatCompletionsDeploymentName")
index_name = os.environ.get("IndexName")
search_endpoint = os.environ.get("SearchEndpoint")
key = os.environ.get("Key")
key_id = os.environ.get("KeyId")

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default")

client = AzureOpenAI(
    azure_endpoint=endpoint,
    azure_ad_token_provider=token_provider,
    api_version="2024-02-15-preview",
)

completion = client.chat.completions.create(
    model=deployment,
    messages=[
        {
            "role": "user",
            "content": "Who is DRI?",
        },
    ],
    extra_body={
        "data_sources": [
            {
                "type": "elasticsearch",
                "parameters": {
                    "endpoint": search_endpoint,
                    "index_name": index_name,
                    "authentication": {
                        "type": "key_and_key_id",
                        "key": key,
                        "key_id": key_id
                    }
                }
            }
        ]
    }
)

print(completion.model_dump_json(indent=2))


az rest --method POST \
 --uri $AzureOpenAIEndpoint/openai/deployments/$ChatCompletionsDeploymentName/chat/completions?api-version=2024-02-15-preview \
 --resource https://cognitiveservices.azure.com/ \
 --body \
'
{
    "data_sources": [
      {
        "type": "elasticsearch",
        "parameters": {
          "endpoint": "'$SearchEndpoint'",
          "index_name": "'$IndexName'",
          "authentication": {
            "type": "key_and_key_id",
            "key": "'$Key'",
            "key_id": "'$KeyId'"
          }
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Who is DRI?"
      }
    ]
}
'

共用方式為