AI 助理
备案控制台
文档
输入文档关键字查找
首页检索分析服务 Elasticsearch版操作指南AI搜索阿里云Elasticsearch Inference API自定义模型推理服务

自定义模型推理服务

更新时间：2025-03-14 05:10:18
产品详情
我的收藏

阿里云Elasticsearch通过扩展Inference API，提供了一种灵活且高效的方式来部署和管理自定义AI模型。该功能适用于推荐系统、图像检索、自然语言处理等多种场景，帮助您将自定义AI模型与Elasticsearch高性能引擎快速结合，从而提升业务应用的效率与准确性。

背景信息

  • Elasticsearch（简称ES）官方提供的Inference API支持调用Hugging Face、OpenAI 等外部平台的推理模型服务，更多信息请参见Create inference API。

  • 阿里云Elasticsearch（简称ES）通过扩展Inference API，支持调用除官方模型外的其他国内常用平台的模型。您可以在ES中自定义模型推理服务，我们将自定义的模型ID适配Inference API的模型ID，把embedding、rerank等流程整合在ES的读写流程中，帮助您将AI模型能力与ES高性能引擎快速结合，服务于实际业务场景。我们为常见的模型平台提供了标准化模板，请参考以便于快捷配置：

创建推理模型

通用模板

PUT _inference/<task_type>/<inference_id>
{
  "service": "alibaba-cloud-custom-model",
  "service_settings": {
    "secret_parameters": {
      ...
    },
    "url": "<url>",
    "path": {
      "<path>": {
        "<method>": {
          "query_string": "<query_string>",
          "headers": {
            ...
          },
          "request": {
            "format": "string",
            "content": "<content>"
          },
          "response": {
            "json_parser":{
              ...
            }
          }
        }
      }
    }
  },
  "task_settings": {
    "parameters":{
      ...
    }
  }
}

参数说明

参数

类型

是否必填

说明

参数

类型

是否必填

说明

<task_type>

/

是

模型类型，可选值有：

  • text_embedding

  • sparse_embedding

  • rerank

  • completion

  • custom（对于非上述四种类型的推理模型，或者有需要得到完整Response的需求，则使用custom类型，此时result为完整的http response）。

inference_id

/

是

自定义参数，创建的推理模型名。

service

string

是

指定使用的服务，使用阿里云自定义模型为alibaba-cloud-custom-model。

service_settings

/

是

服务设置。

secret_parameters

object

是

敏感参数（如api_key、token等）在secret_parameters中进行配置，并在需要的地方使用占位符进行替换。

<url>

string

是

使用服务的url地址。

<path>

string

是

使用服务的path，和url一起组成服务的调用地址。

<method>

string

是

http请求的方法，支持POST、PUT以及GET。

<query_string>

string

否

http请求的query string参数。

headers

object

否

http请求的header参数。

request

object

是

自定义模型的http request请求。

request.format

string

是

request请求的body类型，目前支持string。

request.content

string

是

request请求的body结构，需要传入JSON格式http request body的string转义结果。

response

object

否

当task_type为text_embedding、sparse_embedding、rerank或completion时，需要配置对应的response.json_parser。

response.json_parser

object

当<task_type>为custom时，不需要填写，为其余类型时，需要填写对应的参数。

定义对http response的解析方式，使用json path的语法将response解析为es可识别的对象。

response.json_parser.text_embeddings

string

仅当<task_type>为text_embedding时必填。

task_type为text_embedding时需要配置该参数，解析text_embedding的路径。

response.json_parser.sparse_result

object

仅当<task_type>为sparse_embedding时必填。

task_type为sparse_embedding时需要配置该参数。

response.json_parser.sparse_result.path

string

解析 sparse_result的路径。

response.json_parser.sparse_result.value.sparse_token

string

解析sparse_token的路径。

response.json_parser.sparse_result.value.sparse_weight

string

解析sparse_weight的路径。

response.json_parser.relevance_score

string

当<task_type>为rerank时必填，为其余类型时，不能填写。

解析rerank relevance_score的路径。

response.json_parser.reranked_index

string

否

解析rerank reranked_index的路径。

response.json_parser.document_text

string

否

解析rerank document_text的路径。

response.json_parser.completion_result

string

当<task_type>为completion时必填，为其余类型时，不能填写。

解析completion completion_result的路径。

task_settings.parameters

object

否

自定义参数，在parameters中进行配置，并在需要的地方使用占位符进行替换。

模型接口的可选参数均在task_settings.parameters中以推理模型的默认值参数配置，如需修改，可以在创建接口时配置为所需值，或是在调用接口时配置task_settings.parameters参数。

Response参数用于对http请求返回的Response进行解析，将其转化为ES可识别的对象，从而使得模型推理服务可以与ES的写入以及查询流程整合，我们使用jsonPath表达式来对Response进行解析。

ES支持text_embedding、sparse_embedding、rerank、completion以及custom类型的自定义模型，除了custom类型没有Response参数以外，剩下四个类型的Response格式是不一样的，这里为每种类型的Response格式举个例子：

text_embedding类型
sparse_embedding类型
rerank类型
completion类型

对于text_embedding类型，输入是string或List<string>，需要一个List<List<Float>>类型的结果，对应每个输入文本的向量结果。

下面是一个示例的Response（响应结果）：

{
    "request_id": "B4AB89C8-B135-****-A6F8-2BAB801A2CE4",
    "latency": 38,
    "usage": {
        "token_count": 3072
    },
    "result": {
        "embeddings": [
            {
                "index": 0,
                "embedding": [
                    -0.02868066355586052,
                    0.022033605724573135,
                    ...
                ]
            }
        ]
    }
}

对应的参数配置：

"response":{
	"json_parser":{
		"text_embeddings":"$.result.embeddings[*].embedding"
	}
}

对于sparse_embedding类型，输入是string或List<string>，需要一个List<List<string>的token以及一个List<List<Float>的weight。

示例Response（响应结果）：

{
	"request_id": "75C50B5B-E79E-4930-****-F48DBB392231",
	"latency": 22,
	"usage": {
		"token_count": 11
	},
	"result": {
		"sparse_embeddings": [
			{
				"index": 0,
				"embedding": [
					{
						"tokenId": 6,
						"weight": 0.10137939453125
					},
					{
						"tokenId": 163040,
						"weight": 0.2841796875
					},
					{
						"tokenId": 354,
						"weight": 0.1431884765625
					},
					{
						"tokenId": 5998,
						"weight": 0.161376953125
					},
					{
						"tokenId": 8550,
						"weight": 0.2388916015625
					},
					{
						"tokenId": 2017,
						"weight": 0.1614990234375
					}
				]
			},
			{
				"index": 1,
				"embedding": [
					{
						"tokenId": 9803,
						"weight": 0.1951904296875
					},
					{
						"tokenId": 86250,
						"weight": 0.317138671875
					},
					{
						"tokenId": 5889,
						"weight": 0.17529296875
					},
					{
						"tokenId": 2564,
						"weight": 0.11614990234375
					},
					{
						"tokenId": 59529,
						"weight": 0.1666259765625
					}
				]
			}
		]
	}
}

对应的参数配置：

"response":{
	"json_parser":{
		"sparse_result":{
			"path":"$.result.sparse_embeddings[*]",
			"value":{
				"sparse_token":"$.embedding[*].token_id",
				"sparse_weight":"$.embedding[*].weight"   
			}
		}
	}
}

对于rerank类型，需要一个List<Float>类型的score（输入文本针对query的排序分数），可选的List<int>的index（本doc在输入文本数组中的位置索引值，不填则是默认顺序），以及一个可选的List<string>的text（排序结果对应的输入文本原文）。

示例Response（响应结果）：

{
  "request_id":"24B004E0-ADEF-****-879B-F28359BFAD1D",
  "latency":19,
  "usage":{
      "doc_count":3
  },
  "result":{
      "scores":[
        {
          "index":0,"score":0.45026873385713345
        },
        {
          "index":1,"score":1.1412238544346029E-4
        },
        {
          "index":2,"score":8.029784284533197E-5
        }
      ]
    }
  }

对应的参数配置：

"response":{
	"json_parser":{
		"relevance_score":"$.result.scores[*].score",
		"reranked_index":"$.result.scores[*].index"
	}
}

对于completion类型，需要一个List<string>类型的结果。

示例Response（响应结果）：

{
  "request_id": "450fcb80-f796-****-8d69-e1e86d29aa9f",
  "latency": 564.903929,
  "result": {
    "text":"郑州是一个历史文化悠久且现代化的城市，有很多好玩的地方。以下是一些推荐的旅游景点：..."
  }
  "usage": {
      "output_tokens": 6320,
      "input_tokens": 35,
      "total_tokens": 6355,
  }
  
}

对应的参数配置：

"response":{
	"json_parser":{
		"completion_result":"$.result.text"
	}
}

各类型创建示例

TEXT_EMBEDDING（文本向量）
SPARSE_EMBEDDING（文本稀疏向量）
RERANK（排序服务）
COMPLETION（内容生成服务）
CUSTOM（自定义服务）
PUT _inference/text_embedding/<model_id>
{
  "service":"alibaba-cloud-custom-model",
  "service_settings":{
    "secret_parameters":{
      <secret_parameters参数>
    },
    "url":"<替换为您的url>",
    "path":{
      "<替换为您的path>":{
        "POST":{
          "query_string": "<query_string参数>",
          "headers":{
            <header参数>
          },
          "request":{
            "format":"string",
            "content":"<替换为模型的request格式>"
          },
          "response":{
            "json_parser":{
              "text_embeddings":"<解析text_embedding的路径>"
            }
          }
        }
      }
    }
  },
  "task_settings":{
    "parameters":{
      <parameters参数>
    }
  }
}
PUT _inference/sparse_embedding/<model_id>
{
  "service":"alibaba-cloud-custom-model",
  "service_settings":{
    "secret_parameters":{
      <secret_parameters参数>
    },
    "url":"<替换为您的url>",
    "path":{
      "<替换为您的path>":{
        "<method>":{
          "query_string": "<query_string参数>",
          "headers":{
            <header参数>
          },
          "request":{
            "format":"string",
            "content":"<替换为模型的request格式>"
          },
          "response":{
            "json_parser":{
              "sparse_result":{
                "path":"<解析sparse_embedding的路径>",
                "value":{
                  "sparse_token":"<解析sparse_embedding_token的路径>",
                  "sparse_weight":"<解析sparse_embedding_weight的路径>",   
                }
              }
            }
          }
        }
      }
    }
  },
  "task_settings":{
    "parameters":{
      <parameters参数>
    }
  }
}
PUT _inference/rerank/<model_id>
{
  "service":"alibaba-cloud-custom-model",
  "service_settings":{
    "secret_parameters":{
      <secret_parameters参数>
    },
    "url":"<替换为您的url>",
    "path":{
      "<替换为您的path>":{
        "<method>":{
          "query_string": "<query_string参数>",
          "headers":{
            <header参数>
          },
          "request":{
            "format":"string",
            "content":"<替换为模型的request格式>"
          },
          "response":{
            "json_parser":{
              "relevance_score":"<解析rerank relevance_score的路径>",
              "reranked_index":"<解析rerank reranked_index的路径>",
              "document_text":"<解析rerank document_text的路径>"
            }
          }
        }
      }
    }
  }
}
PUT _inference/completion/<model_id>
{
  "service":"alibaba-cloud-custom-model",
  "service_settings":{
    "secret_parameters":{
      <secret_parameters参数>
    },
    "url":"<替换为您的url>",
    "path":{
      "<替换为您的path>":{
        "<method>":{
          "query_string": "<query_string参数>",
          "headers":{
            <header参数>
          },
          "request":{
            "format":"string",
            "content":"<替换为模型的request格式>"
          },
          "response":{
            "json_parser":{
              "completion_result":"<解析completion的路径>"
            }
          }
        }
      }
    }
  },
  "task_settings":{
    "parameters":{
      <parameters参数>
    }
  }
}

对于目前ES暂不支持的模型类型，或者用户需要获取完整响应的情况，可以将模型类型配置为自定义（custom）。在此情况下，ES返回的响应中将包含完整的模型响应。

text_embedding、sparse_embedding、rerank以及completion模型也可以定义为custom。

PUT _inference/custom/<model_id>
{
  "service":"alibaba-cloud-custom-model",
  "service_settings":{
    "secret_parameters":{
      <secret_parameters参数>
    },
    "url":"<替换为您的url>",
    "path":{
      "<替换为您的path>":{
        "<method>":{
          "query_string": "<query_string参数>",
          "headers":{
            <header参数>
          },
          "request":{
            "format":"string",
            "content":"<替换为模型的request格式>"
          }
        }
      }
    }
  },
  "task_settings":{
    "parameters":{
      <parameters参数>
    }
  }
}

获取推理模型

语法

GET /_inference/_all

GET /_inference/<inference_id>

GET /_inference/<task_type>/_all

GET /_inference/<task_type>/<inference_id>

参数说明

参数

内容

参数

内容

<inference_id>

自定义的inference endpoint标识符。

<task_type>

inference接口类型，支持的值：

  • text_embedding

  • sparse_embedding

  • rerank

  • completion

  • custom

示例

获取示例：

GET _inference/_all

Response（响应结果）：

{
  "endpoints": [
    {
      "inference_id": "os_deployment_emb",
      "task_type": "text_embedding",
      "service": "alibaba-cloud-custom-model",
      "service_settings": {
        "url": "http://xxxx.opensearch.aliyuncs.com",
        "path": {
"/v3/openapi/deployments/xxx/predict": {
            "POST": {
              "headers": {
                "Authorization": "Bearer ${api_key}",
                "Token": "${Token}"
              },
              "request": {
                "format": "string",
                "content": """{"input":${input},"input_type":"${input_type}"}"""
              },
              "response": {
                "json_parser": {
                  "text_embeddings": "$.embeddings[*].embedding"
                }
              }
            }
          }
        },
        "rate_limit": {
          "requests_per_minute": 10000
        }
      },
      "task_settings": {
        "parameters": {
          "input_type": "document"
        }
      }
    }
  ]
}

调用推理模型

语法

POST /_inference/<inference_id>

POST /_inference/<task_type>/<inference_id>

参数说明

path parameters（路径参数）:

参数

内容

参数

内容

<inference_id>

自定义的inference endpoint标识符。

<task_type>

inference接口类型，支持的值：

  • text_embedding

  • sparse_embedding

  • rerank

  • completion

  • custom

query parameters（查询字符串参数）:

参数

内容

参数

内容

timeout

可选填，string，控制等待请求的超时时长，默认为30s

request body（请求体参数）:

参数

内容

参数

内容

input

必填，string or array of strings，调用模型时的输入文本。

query

可选填，string，仅用于rerank接口，输入查询内容。

task_settings

可选填，object，本次调用模型请求的task_settings配置，本次请求中这个配置会覆盖创建模型推理时的task_settings配置。

示例

text_embedding

调用示例：

POST _inference/text_embedding/os_deployment_emb
{
  "input":"hello world"
}

Response（响应结果）：

{
  "text_embedding": [
    {
      "embedding": [
        -0.026062012,
        0.01574707,
        -0.03842163,
        0.012580872,
        ...
      ]
    }
  ]
}

rerank

调用示例：

POST _inference/rerank/os_deployment_custom_rerank
{
  "input": ["luke", "like", "leia", "chewy","r2d2", "star", "wars"],
  "query": "star wars main character"
}

Response（响应结果）：

{
  "rerank": [
    {
      "index": 0,
      "relevance_score": 0.8502201
    },
    {
      "index": 1,
      "relevance_score": 0.062216982
    },
    {
      "index": 2,
      "relevance_score": 0.60352296
    },
    {
      "index": 3,
      "relevance_score": 0.35611072
    },
    {
      "index": 4,
      "relevance_score": 0.40951595
    },
    {
      "index": 5,
      "relevance_score": 0.16277891
    },
    {
      "index": 6,
      "relevance_score": 0.12918286
    }
  ]
}

删除推理模型

语法

DELETE /_inference/<inference_id>

DELETE /_inference/<task_type>/<inference_id>

参数说明

参数

内容

参数

内容

<inference_id>

自定义的inference endpoint标识符。

对应示例：DELETE /_inference/<inference_id>。

<task_type>

inference接口类型，支持的值：

  • text_embedding

  • sparse_embedding

  • rerank

  • completion

  • custom

对应示例：DELETE /_inference/<task_type>/<inference_id>。

示例

删除示例：

DELETE _inference/custom-rerank

Response（响应结果）：

{
  "acknowledged": true,
  "pipelines": []
}

上一篇：AI搜索开放平台内置模型服务下一篇：配置模板：AI搜索开放平台
  • 本页导读 （1）
  • 背景信息
  • 创建推理模型
  • 通用模板
  • 参数说明
  • 各类型创建示例
  • 获取推理模型
  • 语法
  • 参数说明
  • 示例
  • 调用推理模型
  • 语法
  • 参数说明
  • 示例
  • 删除推理模型
  • 语法
  • 参数说明
  • 示例