Todos os produtos
Search
Central de documentação

Alibaba Cloud Model Studio:Retrieve

Última atualização: Sep 02, 2026

Obtém informações de uma base de conhecimento especificada.

Descrição da operação

  • Como chamar: Recomendamos usar o SDK do Alibaba Cloud Model Studio mais recente para chamar esta API. O SDK simplifica as chamadas de API ao lidar com o cálculo complexo de assinatura.

  • Permissões necessárias:

    • Usuário RAM (subconta): Para chamar esta API, um usuário RAM deve receber permissões de API para o Alibaba Cloud Model Studio e ingressar em um workspace. Você pode usar a política AliyunBailianDataFullAccess, que inclui a permissão necessária sfm:Retrieve.
    • Conta Alibaba Cloud (conta principal): Esta conta possui as permissões necessárias por padrão e pode chamar a API diretamente.
  • Latência de resposta: Esta chamada de API envolve operações complexas de recuperação e correspondência, o que pode causar tempos de resposta mais longos. Recomendamos configurar tempos limite de solicitação e estratégias de nova tentativa apropriados.

  • Idempotência: Esta API é idempotente.

Experimente agora

Experimente esta API no OpenAPI Explorer, sem necessidade de assinatura manual. Chamadas bem-sucedidas geram automaticamente código SDK correspondente aos seus parâmetros. Faça o download com segurança de credenciais integrada para uso local.

Autorização RAM

A tabela abaixo descreve a autorização necessária para chamar esta API. Você pode defini-la em uma política do Resource Access Management (RAM). As colunas da tabela estão detalhadas abaixo:

  • Ação: As ações que podem ser usadas no elemento Action das instruções de política de permissão do RAM para conceder permissões para executar a operação.

  • API: A API que você pode chamar para executar a ação.

  • Nível de acesso: O nível de acesso predefinido concedido para cada API. Valores válidos: create, list, get, update e delete.

  • Tipo de recurso: O tipo de recurso que suporta autorização para executar a ação. Indica se a ação suporta permissão em nível de recurso. O recurso especificado deve ser compatível com a ação. Caso contrário, a política será ineficaz.

    • Para APIs com permissões em nível de recurso, os tipos de recursos obrigatórios são marcados com um asterisco (*). Especifique o Nome de Recurso Alibaba Cloud (ARN) correspondente no elemento Resource da política.
    • Para APIs sem permissões em nível de recurso, é exibido como Todos os Recursos. Use um asterisco (*) no elemento Resource da política.
  • Chave de condição: As chaves de condição definidas pelo serviço. A chave permite controle granular, aplicando-se somente a ações ou a ações associadas a recursos específicos. Além das chaves de condição específicas do serviço, o Alibaba Cloud fornece um conjunto de chaves de condição comuns aplicáveis a todos os serviços compatíveis com RAM.

  • Ação dependente: As ações dependentes necessárias para executar a ação. Para concluir a ação, o usuário RAM ou a função RAM deve ter permissões para executar todas as ações dependentes.

Ação

Nível de acesso

Tipo de recurso

Chave de condição

Ação dependente

sfm:Retrieve

none

*All Resource

*

NenhumaNenhuma

Sintaxe da solicitação

POST /{WorkspaceId}/index/retrieve HTTP/1.1

Parâmetros de caminho

Parâmetro

Tipo

Obrigatório

Descrição

Exemplo

WorkspaceId

string

Sim

O ID do workspace que contém a base de conhecimento. Para mais informações, consulte Como usar workspaces.

llm-3shx2gu255oqxxxx

Parâmetros da solicitação

Parâmetro

Tipo

Obrigatório

Descrição

Exemplo

Query

string

Não

A consulta, que é o prompt original do usuário. Não há limites para o comprimento da consulta.

阿里云百炼平台介绍

DenseSimilarityTopK

integer

Não

O número de top-K chunks de texto semelhantes a serem recuperados usando recuperação vetorial. Isso é obtido gerando uma representação vetorial da consulta e pesquisando na base de conhecimento os K chunks de texto com os vetores mais semelhantes. O valor deve ser um número inteiro de 0 a 100. A soma de DenseSimilarityTopK e SparseSimilarityTopK não deve exceder 200.

Valor padrão: 100.

100

EnableReranking

boolean

Não

Especifica se o reranking deve ser ativado. Para mais informações, consulte Base de conhecimento. Valores válidos:

  • true: Ativa o reranking.

  • false: Desativa o reranking.

Valor padrão: true.

Valores válidos:

  • true :

    Ativado.

  • false :

    Desativado.

true

EnableRewrite

boolean

Não

Especifica se a reescrita de consulta conversacional deve ser ativada. Valores válidos:

  • true: Ativa a reescrita de consulta conversacional.

  • false: Desativa a reescrita de consulta conversacional.

Valor padrão: false.

Valores válidos:

  • true :

    Ativado.

  • false :

    Desativado.

false

Rerank

array<object>

Não

As configurações de reranking.

object

Não

Um objeto que contém configurações de reranking.

ModelName

string

Não

O modelo de reranking a ser usado. Especificar um modelo aqui substitui o modelo padrão selecionado quando a base de conhecimento foi criada. Valores válidos:

  • gte-rerank-hybrid: Executa o reranking usando o modelo gte-rerank (híbrido).

  • gte-rerank: Executa o reranking usando o modelo gte-rerank.

Se você não especificar este parâmetro, o modelo configurado para a base de conhecimento será usado.

Use gte-rerank apenas para classificação semântica. Recomendamos gte-rerank-hybrid se você precisar de recursos de classificação semântica e correspondência de texto para maior relevância.

Valores válidos:

  • gte-rerank-hybrid :

    Executa o reranking usando o modelo gte-rerank (híbrido).

  • gte-rerank :

    Executa o reranking usando o modelo gte-rerank.

gte-rerank-hybrid

RerankMode

string

Não

Este parâmetro ainda não está disponível. Não especifique um valor para ele.

[_single.params.Rerank.items.RerankMode.enum.similar: 相似模式。]`similar`: Modo de similaridade. [_single.params.Rerank.items.RerankMode.enum.custom: 自定义模式。]`custom`: Modo personalizado. [_single.params.Rerank.items.RerankMode.enum.qa:(默认值) 问答模式。]`qa`: (Padrão) Modo de perguntas e respostas. [parameters.4.schema.items.properties.RerankMode.enumValueTitles.similar: 相似模式。]`similar`: Modo de similaridade. [parameters.4.schema.items.properties.RerankMode.enumValueTitles.custom: 自定义模式。]`custom`: Modo personalizado. [parameters.4.schema.items.properties.RerankMode.enumValueTitles.qa:(默认值) 问答模式。]`qa`: (Padrão) Modo de perguntas e respostas.

Valores válidos:

  • similar: 相似模式。 :

    similar: Similarity mode.

  • custom: 自定义模式。 :

    custom: Custom mode.

  • qa:(默认值) 问答模式。 :

    qa: (Default) Q&A mode.

qa

RerankInstruct

string

Não

Este parâmetro ainda não está disponível. Não especifique um valor para ele.

RerankMinScore

number

Não

O limite de similaridade para reranking. Apenas chunks de texto com uma pontuação de similaridade maior que este valor são retornados. O valor deve estar entre 0,01 e 1,00, inclusive. Este parâmetro substitui a configuração de limite de similaridade da base de conhecimento.

Se não for especificado, o limite configurado para a base de conhecimento será usado.

0.20

RerankTopN

integer

Não

O número de chunks de texto mais bem classificados a serem retornados após o reranking. O valor deve ser um número inteiro de 1 a 20. Valor padrão: 5.

5

Rewrite

array<object>

Não

Configuração para reescrita de consulta conversacional.

object

Não

Um objeto que contém configurações para reescrita de consulta conversacional.

ModelName

string

Não

Especifica o modelo para reescrita de consulta conversacional, que reescreve automaticamente a consulta original com base no contexto da conversa para melhorar os resultados da recuperação. Valor válido:

  • conv-rewrite-qwen-1.8b: O único modelo atualmente suportado para este recurso.

Se este parâmetro não for especificado, conv-rewrite-qwen-1.8b será usado por padrão.

Valores válidos:

  • conv-rewrite-qwen-1.8b :

    O modelo conv-rewrite-qwen-1.8b.

conv-rewrite-qwen-1.8b

SparseSimilarityTopK

integer

Não

O número de top-K chunks de texto a serem recuperados usando recuperação por palavras-chave. Este recurso encontra chunks de texto na base de conhecimento que correspondem exatamente às palavras-chave na consulta. Ele ajuda a filtrar chunks de texto irrelevantes e a fornecer resultados mais precisos. O valor deve ser um número inteiro de 0 a 100. A soma de DenseSimilarityTopK e SparseSimilarityTopK não deve exceder 200.

Valor padrão: 100.

100

IndexId

string

Sim

O ID da base de conhecimento. Este é o valor Data.Id retornado pela operação CreateIndex.

  • Certifique-se de que a base de conhecimento especificada exista e não tenha sido excluída.

5pwe0mxxxx

SaveRetrieverHistory

boolean

Não

Especifica se o histórico de recuperação deve ser salvo para fins de teste. Valores válidos:

  • true: Salva o histórico de recuperação.

  • false: Não salva o histórico de recuperação.

Valor padrão: false.

false

SearchFilters

array<object>

Não

Especifica condições de recuperação personalizadas, como tags, para filtrar resultados de recuperação semântica e excluir informações irrelevantes. A lógica de filtragem é aplicada apenas quando o parâmetro is_displayed_chunk_content é definido como true. Para mais informações, consulte SearchFilters para uma base de conhecimento.

object

Não

Um objeto de condição de pesquisa.

string

Não

Images

array

Não

As URLs das imagens a serem incluídas na consulta.

string

Não

Ao recuperar informações de uma base de conhecimento de perguntas e respostas baseada em imagens, você pode fornecer URLs de imagens. Se existir um índice de imagens na base de conhecimento, o sistema converte a imagem de entrada em um vetor para recuperar registros relevantes. Se não existir um índice de imagens, a imagem de entrada não será usada para recuperação.

Este campo não é suportado para bases de conhecimento do tipo pesquisa de documentos ou consulta de dados. Este campo não tem efeito se especificado.

Certifique-se de que o link seja acessível publicamente e aponte para um arquivo de imagem válido. Exemplo: https://example.com/downloads/pic.jpg

https://example.com/downloads/pic.jpg

QueryHistory

array<object>

Não

O histórico de conversas, usado para reescrita de consulta conversacional. Este parâmetro é eficaz apenas quando EnableRewrite é definido como true.

object

Não

role

string

Não

A função da entidade que enviou a mensagem.

Valores válidos:

  • user: Indica que o content é do usuário final.

  • assistant: Indica que o content é uma resposta do aplicativo Model Studio.

user

content

string

Não

O conteúdo da mensagem para a role especificada.

代表一段文本。

Extra

object

Não

uniqueId

string

Não

Elementos de resposta

Elemento

Tipo

Descrição

Exemplo

object

Code

string

O código de erro.

Index.InvalidParameter

Data

object

Os dados de negócios retornados pela API.

Nodes

array<object>

Uma matriz de chunks de texto recuperados.

object

Um objeto de chunk de texto.

Metadata

any

A map of metadata for the text chunk.

For document search knowledge bases, the file_path field in the metadata map is not applicable and should not be used in your application code.

When you retrieve data from a document search knowledge base, if a text chunk contains an image, its URL is returned in the image_url field of the metadata map. This URL expires.

{ "parent": "", "file_path": "https://***", "image_url": [ "http://***" ], "nid": "***", "title": "阿里云百炼文档", "doc_id": "doc_***", "content": "阿里云百炼是基于通义大模型、行业大模型以及三方大模型的一站式大模型开发平台。面向企业客户和个人开发者,提供完整的模型服务工具和全链路应用开发套件,预置丰富的能力插件,提供API及SDK等便捷的集成方式,高效完成大模型应用构建", "workspace_id": "ws_***", "hier_title": "阿里云百炼文档", "doc_name": "阿里云百炼文档介绍.pdpf", "pipeline_id": "rhd***", "_id": "ws_***" }

Score

number

The similarity score of the text chunk, ranging from 0 to 1.

0.3

Text

string

The content of the text chunk.

阿里云百炼是基于通义大模型、行业大模型以及三方大模型的一站式大模型开发平台。面向企业客户和个人开发者,提供完整的模型服务工具和全链路应用开发套件,预置丰富的能力插件,提供API及SDK等便捷的集成方式,高效完成大模型应用构建。

Message

string

A mensagem de erro.

Required parameter(%s) missing or invalid, please check the request parameters.

RequestId

string

O ID da solicitação.

17204B98-7734-4F9A-8464-2446A84821CA

Status

string

O código de status HTTP da resposta.

200

Success

boolean

Indica se a chamada de API foi bem-sucedida. Valores válidos:

  • true: A chamada foi bem-sucedida.

  • false: A chamada falhou.

true

Exemplos

Resposta de sucesso

JSON formato

{
  "Code": "Index.InvalidParameter",
  "Data": {
    "Nodes": [
      {
        "Metadata": "{\n  \"parent\": \"\",\n  \"file_path\": \"https://***\",\n  \"image_url\": [\n    \"http://***\"\n  ],\n  \"nid\": \"***\",\n  \"title\": \"阿里云百炼文档\",\n  \"doc_id\": \"doc_***\",\n  \"content\": \"阿里云百炼是基于通义大模型、行业大模型以及三方大模型的一站式大模型开发平台。面向企业客户和个人开发者,提供完整的模型服务工具和全链路应用开发套件,预置丰富的能力插件,提供API及SDK等便捷的集成方式,高效完成大模型应用构建\",\n  \"workspace_id\": \"ws_***\",\n  \"hier_title\": \"阿里云百炼文档\",\n  \"doc_name\": \"阿里云百炼文档介绍.pdpf\",\n  \"pipeline_id\": \"rhd***\",\n  \"_id\": \"ws_***\"\n}",
        "Score": 0.3,
        "Text": "阿里云百炼是基于通义大模型、行业大模型以及三方大模型的一站式大模型开发平台。面向企业客户和个人开发者,提供完整的模型服务工具和全链路应用开发套件,预置丰富的能力插件,提供API及SDK等便捷的集成方式,高效完成大模型应用构建。"
      }
    ]
  },
  "Message": "Required parameter(%s) missing or invalid, please check the request parameters.",
  "RequestId": "17204B98-7734-4F9A-8464-2446A84821CA",
  "Status": "200",
  "Success": true
}

Códigos de erro

Consulte Códigos de Erro para uma lista completa.

Notas de versão

Consulte Notas de Versão para uma lista completa.