Справочник по API данных в Azure OpenAI

2025-07-02

В этой статье приведена справочная документация по Python и REST для нового API OpenAI в Azure Data API. Последняя версия API — 2024-05-01-previewспецификация Swagger.

Замечание

Так как версия 2024-02-15-preview API мы представили следующие критические изменения по сравнению с более ранними версиями API:

Путь API изменяется с /extensions/chat/completions/chat/completions.
Соглашение об именовании ключей свойств и значений перечисления изменяется с верблюжьего регистра на регистр змеи. Пример: deploymentName изменен на deployment_name.
Тип AzureCognitiveSearch источника данных изменяется на azure_search.
Ссылки и намерения перемещаются из сообщений контекста помощника в корневой уровень контекста сообщения помощника с явным определением схемы.

POST {endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

Поддерживаемые версии

2024-02-15-preview Спецификация Swagger.
2024-02-01 Спецификация Swagger.
2024-05-01-preview Спецификация Swagger

Замечание

Pinecone и Elasticsearch поддерживаются в качестве предварительной версии.

Параметры URI

Имя	В	Тип	Обязательно	Описание
`deployment-id`	путь	струна	Верно	Указывает имя развертывания модели завершения чата, используемое для этого запроса.
`endpoint`	путь	струна	Верно	Конечные точки Azure OpenAI. Например: `https://{YOUR_RESOURCE_NAME}.openai.azure.com`
`api-version`	запрос	струна	Верно	Версия API, используемая для данной операции.

Основное содержание запроса

Текст запроса наследует ту же схему запроса API завершения чата. В этой таблице показаны параметры, уникальные для Azure OpenAI в данных.

Имя	Тип	Обязательно	Описание
`data_sources`	Источник данных[]	Верно	Записи конфигурации для Azure OpenAI в данных. В массиве должен быть ровно один элемент. Если `data_sources` оно не предоставлено, служба использует модель завершения чата напрямую и не использует Azure OpenAI On Your Data. При указании `data_sources` параметра вы не сможете использовать `logprobs` параметры или `top_logprobs` параметры.

Основная часть ответа

Текст ответа наследует ту же схему ответа API завершения чата. В сообщении чата ответа есть context свойство, которое добавляется для Azure OpenAI On Your Data.

Сообщение чата

Схема сообщения помощника по ответу наследует от сообщения помощника о завершении чата и расширяется с помощью свойства context.

Имя	Тип	Обязательно	Описание
`context`	Контекст	Неправда	Представляет добавочные шаги, выполняемые Azure OpenAI On Your Data при обработке запроса, включая извлеченные документы.

Контекст

Имя	Тип	Обязательно	Описание
`citations`	Ссылка[]	Неправда	Результат извлечения источника данных, используемый для создания сообщения помощника в ответе. Клиенты могут отображать ссылки из ссылок.
`intent`	струна	Неправда	Обнаруженная цель из журнала чата. Передача предыдущего намерения больше не требуется. Игнорировать это свойство.
`all_retrieved_documents`	Извлеченные документы[]	Неправда	Все извлеченные документы.

Цитата

Имя	Тип	Обязательно	Описание
`content`	струна	Верно	Содержимое ссылки.
`title`	струна	Неправда	Заголовок ссылки.
`url`	струна	Неправда	URL-адрес ссылки.
`filepath`	струна	Неправда	Путь к файлу ссылки.
`chunk_id`	струна	Неправда	Идентификатор фрагмента ссылки.

Извлеченные документы

Имя	Тип	Обязательно	Описание
`search_queries`	строка[]	Верно	Поисковые запросы, используемые для извлечения документа.
`data_source_index`	целое число	Верно	Индекс источника данных.
`original_search_score`	двойной	Верно	Исходная оценка поиска извлеченного документа.
`rerank_score`	двойной	Неправда	Оценка повторного использования извлеченного документа.
`filter_reason`	струна	Неправда	Представляет обоснование фильтрации документа. Если документ не проходит фильтрацию, это поле останется неустановленным. `score` Если документ фильтруется по пороговой оценке исходного поиска, определенному по `strictness`значению. `rerank` Если документ не фильтруется по исходному порогу оценки поиска, но фильтруется по оценке повторного выполнения и`top_n_documents`.

Источник данных

В этом списке показаны поддерживаемые источники данных.

Примеры

В этом примере показано, как передать журнал бесед для улучшения результатов.

Необходимые условия:

Настройте назначения ролей из назначаемого системой Azure OpenAI управляемого удостоверения в службу поиска Azure. Обязательные роли: Search Index Data Reader, Search Service Contributor.
Настройте назначения ролей от пользователя к ресурсу Azure OpenAI. Требуемая роль: Cognitive Services OpenAI User.
Установите Az CLI и запустите az login.
Определите следующие переменные среды: AzureOpenAIEndpoint, ChatCompletionsDeploymentName, SearchEndpointSearchIndex.

export AzureOpenAIEndpoint=https://example.openai.azure.com/
export ChatCompletionsDeploymentName=turbo
export SearchEndpoint=https://example.search.windows.net
export SearchIndex=example-index

Python 1.x
ОТДЫХ

Установите последние пакеты openaipip , 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")
search_endpoint = os.environ.get("SearchEndpoint")
search_index = os.environ.get("SearchIndex")

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-05-01-preview",
)

completion = client.chat.completions.create(
    model=deployment,
    messages=[
        {
            "role": "user",
            "content": "Who is DRI?",
        },
        {
            "role": "assistant",
            "content": "DRI stands for Directly Responsible Individual of a service. Which service are you asking about?"
        },
        {
            "role": "user",
            "content": "Opinion mining service"
        }
    ],
    extra_body={
        "data_sources": [
            {
                "type": "azure_search",
                "parameters": {
                    "endpoint": search_endpoint,
                    "index_name": search_index,
                    "authentication": {
                        "type": "system_assigned_managed_identity"
                    }
                }
            }
        ]
    }
)

print(completion.model_dump_json(indent=2))

# render the citations

content = completion.choices[0].message.content
context = completion.choices[0].message.context
for citation_index, citation in enumerate(context["citations"]):
    citation_reference = f"[doc{citation_index + 1}]"
    url = "https://example.com/?redirect=" + citation["url"] # replace with actual host and encode the URL
    filepath = citation["filepath"]
    title = citation["title"]
    snippet = citation["content"]
    chunk_id = citation["chunk_id"]
    replaced_html = f"<a href='{url}' title='{title}\n{snippet}''>(See from file {filepath}, Part {chunk_id})</a>"
    content = content.replace(citation_reference, replaced_html)
print(content)

az rest --method POST \
 --uri $AzureOpenAIEndpoint/openai/deployments/$ChatCompletionsDeploymentName/chat/completions?api-version=2024-05-01-preview \
 --resource https://cognitiveservices.azure.com/ \
 --body \
'
{
    "data_sources": [
        {
            "type": "azure_search",
            "parameters": {
                "endpoint": "'$SearchEndpoint'",
                "index_name": "'$SearchIndex'",
                "authentication": {
                    "type": "system_assigned_managed_identity"
                }
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "Who is DRI?"
        },
        {
            "role": "assistant",
            "content": "DRI stands for Directly Responsible Individual of a service. Which service are you asking about?"
        },
        {
            "role": "user",
            "content": "Opinion mining service"
        }
    ]
}
'