› › ›

创建推理 API

创建推理 API编辑

此功能处于技术预览阶段，可能会在未来版本中更改或删除。Elastic 将努力解决任何问题，但技术预览版中的功能不受官方 GA 功能的支持 SLA 的约束。

创建推理端点以执行推理任务。

推理 API 使您能够使用某些服务，例如内置机器学习模型（ELSER、E5）、通过 Eland、Cohere、OpenAI、Azure OpenAI 或 Hugging Face 上传的模型。对于内置模型和通过 Eland 上传的模型，推理 API 提供了使用和管理训练模型的另一种方法。但是，如果您不打算使用推理 API 来使用这些模型，或者您想使用非 NLP 模型，请使用机器学习训练模型 API。

请求编辑

PUT /_inference/<task_type>/<inference_id>

先决条件编辑

需要 manage_inference 集群权限（内置的 inference_admin 角色授予此权限）

描述编辑

创建推理 API 使您能够创建推理端点并配置机器学习模型以执行特定的推理任务。

以下服务可通过推理 API 获得

Cohere
ELSER
Hugging Face
OpenAI
Azure OpenAI
Elasticsearch（用于内置模型和通过 Eland 上传的模型）

路径参数编辑

<inference_id>

（必填，字符串）推理端点的唯一标识符。

<task_type>

（必填，字符串）模型将执行的推理任务的类型。可用的任务类型

completion,
rerank,
sparse_embedding,
text_embedding.

请求正文编辑

service

（必填，字符串）指定任务类型支持的服务类型。可用的服务

cohere：指定 text_embedding 或 rerank 任务类型以使用 Cohere 服务。
elser：指定 sparse_embedding 任务类型以使用 ELSER 服务。
hugging_face：指定 text_embedding 任务类型以使用 Hugging Face 服务。
openai：指定 completion 或 text_embedding 任务类型以使用 OpenAI 服务。
azureopenai：指定 text_embedding 任务类型以使用 Azure OpenAI 服务。
elasticsearch：指定 text_embedding 任务类型以使用 E5 内置模型或由 Eland 上传的文本嵌入模型。

service_settings

（必填，对象）用于安装推理模型的设置。这些设置特定于您指定的 service。

cohere 服务的 service_settings

api_key: （必填，字符串）您的 Cohere 帐户的有效 API 密钥。您可以在API 密钥设置页面上找到您的 Cohere API 密钥或创建一个新的 API 密钥。

您只需要在创建推理模型期间提供一次 API 密钥。获取推理 API 不会检索您的 API 密钥。创建推理模型后，您将无法更改关联的 API 密钥。如果要使用其他 API 密钥，请删除推理模型，然后使用相同的名称和更新后的 API 密钥重新创建它。

embedding_type

（可选，字符串）仅适用于 text_embedding。指定您希望返回的嵌入类型。默认为 float。有效值为

byte：将其用于有符号 int8 嵌入（这是 int8 的同义词）。
float：将其用于默认的浮点嵌入。
int8：将其用于有符号 int8 嵌入。

model_id

（可选，字符串）用于推理任务的模型名称。要查看可用的 rerank 模型，请参阅Cohere 文档。

要查看可用的 text_embedding 模型，请参阅Cohere 文档。text_embedding 的默认值为 embed-english-v2.0。

elser 服务的 service_settings

num_allocations: （必填，整数）要创建的模型分配数量。num_allocations 不得超过每个节点的可用处理器数量除以 num_threads。
num_threads: （必填，整数）每个模型分配使用的线程数。num_threads 不得超过每个节点的可用处理器数量除以分配数量。必须是 2 的幂。允许的最大值为 32。

hugging_face 服务的 service_settings

api_key: （必填，字符串）您的 Hugging Face 帐户的有效访问令牌。您可以在设置页面上找到您的 Hugging Face 访问令牌或创建一个新的访问令牌。

url: （必填，字符串）用于请求的 URL 端点。

openai 服务的 service_settings

api_key: （必填，字符串）您的 OpenAI 帐户的有效 API 密钥。您可以在API 密钥部分下的 OpenAI 帐户中找到您的 OpenAI API 密钥。

model_id: （必填，字符串）用于推理任务的模型名称。有关可用文本嵌入模型的列表，请参阅OpenAI 文档。
organization_id: （可选，字符串）您组织的唯一标识符。您可以在设置 > 组织下的 OpenAI 帐户中找到组织 ID。
url: （可选，字符串）用于请求的 URL 端点。可以出于测试目的进行更改。默认为 https://api.openai.com/v1/embeddings。

azureopenai 服务的 service_settings

api_key 或 entra_id: （必填，字符串）您必须提供任一 API 密钥或 Entra ID。如果您两者都不提供，或者两者都提供，则在尝试创建模型时会收到错误消息。有关这些身份验证类型的更多详细信息，请参阅Azure OpenAI 身份验证文档。

您只需要在创建推理模型期间提供一次 API 密钥或 Entra ID。获取推理 API 不会检索您的身份验证凭据。创建推理模型后，您将无法更改关联的 API 密钥或 Entra ID。如果要使用其他 API 密钥或 Entra ID，请删除推理模型，然后使用相同的名称和更新后的 API 密钥重新创建它。您必须定义 api_key 或 entra_id。如果两者都不存在，则会发生错误。

resource_name: （必填，字符串）您的 Azure OpenAI 资源的名称。您可以在 Azure 门户的资源列表中找到您的订阅的资源名称。
deployment_id: （必填，字符串）已部署模型的部署名称。您可以通过链接到您订阅的Azure OpenAI Studio 门户找到您的 Azure OpenAI 部署。
api_version: （必填，字符串）要使用的 Azure API 版本 ID。我们建议使用最新的受支持非预览版本。

elasticsearch 服务的 service_settings

model_id: （必填，字符串）用于推理任务的模型名称。它可以是内置模型的 ID（例如，E5 的 .multilingual-e5-small）或已通过 Eland上传的文本嵌入模型的 ID。
num_allocations: （必填，整数）要创建的模型分配数量。num_allocations 不得超过每个节点的可用处理器数量除以 num_threads。
num_threads: （必填，整数）每个模型分配使用的线程数。num_threads 不得超过每个节点的可用处理器数量除以分配数量。必须是 2 的幂。允许的最大值为 32。

task_settings

（可选，对象）用于配置推理任务的设置。这些设置特定于您指定的 <task_type>。

completion 任务类型的 task_settings

user: （可选，字符串）仅适用于 openai 服务。指定发出请求的用户，可用于滥用检测。

rerank 任务类型的 task_settings

return_documents: （可选，布尔值）仅适用于 cohere 服务。指定是否在结果中返回文档文本。
top_n: （可选，整数）要返回的最相关文档的数量，默认为文档的数量。

text_embedding 任务类型的 task_settings

input_type

（可选，字符串）仅适用于 cohere 服务。指定传递给模型的输入类型。有效值为

classification：将其用于通过文本分类器传递的嵌入。
clusterning：将其用于通过聚类算法运行的嵌入。
ingest：将其用于在向量数据库中存储文档嵌入。
search：将其用于存储针对向量数据库运行的搜索查询的嵌入，以查找相关文档。

truncate

（可选，字符串）仅适用于 cohere 服务。指定 API 如何处理长度超过最大令牌长度的输入。默认为 END。有效值为

NONE：当输入超过最大输入令牌长度时，将返回错误。
START：当输入超过最大输入令牌长度时，将丢弃输入的开头。
END：当输入超过最大输入令牌长度时，将丢弃输入的结尾。

user

（可选，字符串）仅适用于 openai 和 azureopenai 服务。指定发出请求的用户，可用于滥用检测。

completion 任务类型的 task_settings

user: （可选，字符串）仅适用于 openai 服务。指定发出请求的用户，可用于滥用检测。

示例编辑

本节包含每个服务类型的示例 API 调用。

Cohere 服务编辑

以下示例展示了如何创建一个名为 cohere-embeddings 的推理端点来执行 text_embedding 任务类型。

resp = client.inference.put_model(
    task_type="text_embedding",
    inference_id="cohere-embeddings",
    body={
        "service": "cohere",
        "service_settings": {
            "api_key": "<api_key>",
            "model_id": "embed-english-light-v3.0",
            "embedding_type": "byte",
        },
    },
)
print(resp)

PUT _inference/text_embedding/cohere-embeddings
{
    "service": "cohere",
    "service_settings": {
        "api_key": "<api_key>",
        "model_id": "embed-english-light-v3.0",
        "embedding_type": "byte"
    }
}

以下示例展示了如何创建一个名为 cohere-rerank 的推理端点来执行 rerank 任务类型。

resp = client.inference.put_model(
    task_type="rerank",
    inference_id="cohere-rerank",
    body={
        "service": "cohere",
        "service_settings": {
            "api_key": "<API-KEY>",
            "model_id": "rerank-english-v3.0",
        },
        "task_settings": {"top_n": 10, "return_documents": True},
    },
)
print(resp)

PUT _inference/rerank/cohere-rerank
{
    "service": "cohere",
    "service_settings": {
        "api_key": "<API-KEY>",
        "model_id": "rerank-english-v3.0"
    },
    "task_settings": {
        "top_n": 10,
        "return_documents": true
    }
}

有关更多示例，还可以查看Cohere 文档。

通过 Elasticsearch 服务使用 E5编辑

以下示例展示了如何创建一个名为 my-e5-model 的推理端点来执行 text_embedding 任务类型。

resp = client.inference.put_model(
    task_type="text_embedding",
    inference_id="my-e5-model",
    body={
        "service": "elasticsearch",
        "service_settings": {
            "num_allocations": 1,
            "num_threads": 1,
            "model_id": ".multilingual-e5-small",
        },
    },
)
print(resp)

PUT _inference/text_embedding/my-e5-model
{
  "service": "elasticsearch",
  "service_settings": {
    "num_allocations": 1,
    "num_threads": 1,
    "model_id": ".multilingual-e5-small" 
  }
}

model_id 必须是内置 E5 模型之一的 ID。有效值为 .multilingual-e5-small 和 .multilingual-e5-small_linux-x86_64。有关更多详细信息，请参阅E5 模型文档。

ELSER 服务编辑

以下示例展示了如何创建一个名为 my-elser-model 的推理端点来执行 sparse_embedding 任务类型。

resp = client.inference.put_model(
    task_type="sparse_embedding",
    inference_id="my-elser-model",
    body={
        "service": "elser",
        "service_settings": {"num_allocations": 1, "num_threads": 1},
    },
)
print(resp)

PUT _inference/sparse_embedding/my-elser-model
{
  "service": "elser",
  "service_settings": {
    "num_allocations": 1,
    "num_threads": 1
  }
}

示例响应

{
  "inference_id": "my-elser-model",
  "task_type": "sparse_embedding",
  "service": "elser",
  "service_settings": {
    "num_allocations": 1,
    "num_threads": 1
  },
  "task_settings": {}
}

Hugging Face 服务编辑

以下示例展示了如何创建一个名为 hugging-face-embeddings 的推理端点来执行 text_embedding 任务类型。

resp = client.inference.put_model(
    task_type="text_embedding",
    inference_id="hugging-face-embeddings",
    body={
        "service": "hugging_face",
        "service_settings": {
            "api_key": "<access_token>",
            "url": "<url_endpoint>",
        },
    },
)
print(resp)

PUT _inference/text_embedding/hugging-face-embeddings
{
  "service": "hugging_face",
  "service_settings": {
    "api_key": "<access_token>", 
    "url": "<url_endpoint>" 
  }
}

	有效的 Hugging Face 访问令牌。您可以在您帐户的设置页面上找到。
	您在 Hugging Face 上创建的推理端点 URL。

在Hugging Face 端点页面上创建一个新的推理端点以获取端点 URL。在新端点创建页面上选择要使用的模型 - 例如 intfloat/e5-small-v2 - 然后在“高级配置”部分下选择 Sentence Embeddings 任务。创建端点。端点初始化完成后复制 URL。

Hugging Face 服务推荐模型列表

通过 Elasticsearch 服务上传的 Eland 模型编辑

以下示例展示了如何创建一个名为 my-msmarco-minilm-model 的推理端点来执行 text_embedding 任务类型。

resp = client.inference.put_model(
    task_type="text_embedding",
    inference_id="my-msmarco-minilm-model",
    body={
        "service": "elasticsearch",
        "service_settings": {
            "num_allocations": 1,
            "num_threads": 1,
            "model_id": "msmarco-MiniLM-L12-cos-v5",
        },
    },
)
print(resp)

PUT _inference/text_embedding/my-msmarco-minilm-model
{
  "service": "elasticsearch",
  "service_settings": {
    "num_allocations": 1,
    "num_threads": 1,
    "model_id": "msmarco-MiniLM-L12-cos-v5" 
  }
}

model_id 必须是已通过Eland 上传的文本嵌入模型的 ID。

OpenAI 服务编辑

以下示例展示了如何创建一个名为 openai-embeddings 的推理端点来执行 text_embedding 任务类型。

resp = client.inference.put_model(
    task_type="text_embedding",
    inference_id="openai-embeddings",
    body={
        "service": "openai",
        "service_settings": {
            "api_key": "<api_key>",
            "model_id": "text-embedding-ada-002",
        },
    },
)
print(resp)

PUT _inference/text_embedding/openai-embeddings
{
    "service": "openai",
    "service_settings": {
        "api_key": "<api_key>",
        "model_id": "text-embedding-ada-002"
    }
}

下一个示例展示了如何创建一个名为 openai-completion 的推理端点来执行 completion 任务类型。

resp = client.inference.put_model(
    task_type="completion",
    inference_id="openai-completion",
    body={
        "service": "openai",
        "service_settings": {
            "api_key": "<api_key>",
            "model_id": "gpt-3.5-turbo",
        },
    },
)
print(resp)

PUT _inference/completion/openai-completion
{
    "service": "openai",
    "service_settings": {
        "api_key": "<api_key>",
        "model_id": "gpt-3.5-turbo"
    }
}

Azure OpenAI 服务编辑

以下示例展示了如何创建一个名为 azure_openai_embeddings 的推理端点来执行 text_embedding 任务类型。请注意，我们此处未指定模型，因为它已通过我们的 Azure OpenAI 部署定义。

您可以在Azure 模型文档中找到可在部署中选择的嵌入模型列表。

resp = client.inference.put_model(
    task_type="text_embedding",
    inference_id="azure_openai_embeddings",
    body={
        "service": "azureopenai",
        "service_settings": {
            "api_key": "<api_key>",
            "resource_name": "<resource_name>",
            "deployment_id": "<deployment_id>",
            "api_version": "2024-02-01",
        },
    },
)
print(resp)

PUT _inference/text_embedding/azure_openai_embeddings
{
    "service": "azureopenai",
    "service_settings": {
        "api_key": "<api_key>",
        "resource_name": "<resource_name>",
        "deployment_id": "<deployment_id>",
        "api_version": "2024-02-01"
    }
}

« 执行推理 API 信息 API »