AI_GEN_STRUCTURED - Hologres: Central de Documentação do Alibaba Cloud

A ai_gen_structured é uma AI Function do Hologres que gera saída em JSON estruturado conforme um JSON Schema especificado. Este recurso atende a cenários que exigem saída analisável e com formato controlado de modelos de linguagem grandes, como a extração de entidades estruturadas de texto ou informações de anotação de imagens e vídeos.

Pré-requisitos

Sua instância do Hologres deve executar a versão V4.2.4 ou posterior.
O modelo necessário deve estar implantado no console do Hologres. Para mais informações, consulte Managed models.

Sintaxe

Extrair informações estruturadas de texto

ai_gen_structured(
    model_name      TEXT,
    message         TEXT,
    response_format JSON,
    on_error        TEXT DEFAULT 'capture',
    params          JSON DEFAULT '{}'::json
) RETURNS JSON

Extrair informações estruturadas de entrada multimodal, como imagens ou vídeos

ai_gen_structured(
    model_name      TEXT,
    message         TEXT,
    input_file      FILE,
    response_format JSON,
    on_error        TEXT DEFAULT 'capture',
    params          JSON DEFAULT '{}'::json
) RETURNS JSON

Parâmetros

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
model_name	TEXT	Sim	-	Nome do modelo, como `qwen3.7-max` ou `qwen3.7-plus`. Implante o modelo antecipadamente. Para mais informações, consulte Managed models.
message	TEXT	Sim	-	Prompt enviado ao modelo.
input_file	FILE	Não	-	Arquivo de entrada. Compatível apenas com a sobrecarga multimodal. Construa-o com `to_file(uri, endpoint, role_arn)`. Para mais informações, consulte Construct a multimodal input file neste tópico.
response_format	JSON	Sim	-	Definição do formato de saída. Dois modos são compatíveis: `json_schema` e `json_object`. Para mais informações, consulte response_format modes neste tópico.
on_error	TEXT	Não	'capture'	Política de tratamento de erros no nível da linha. Aplica-se apenas a erros ocorridos durante a etapa de inferência do modelo, como quando o modelo retorna um JSON inválido. Valores válidos: `'capture'` (padrão): Se a inferência falhar, a função retornará a mensagem de erro como resultado JSON e a consulta continuará. `'skip'`: Se a inferência falhar, a linha retornará NULL e a consulta prosseguirá. `'abort'`: Se a inferência falhar, o sistema lançará uma exceção e abortará toda a instrução SQL. Para processamento em lote, use `'skip'` ou `'capture'` para evitar que uma única linha com falha aborte toda a consulta. Nota Os seguintes erros de nível de uso não são regidos por on_error e sempre lançam uma exceção diretamente: nome do modelo inexistente; arquivo de entrada inexistente (OSS 404); erros de sintaxe ou lógica SQL.
params	JSON	Não	'{}'	Parâmetros adicionais transmitidos no formato JSON, como `{"temperature": 0.1}`.

Valor de retorno

Retorna um valor do tipo JSON cujo conteúdo está em conformidade com o schema definido em response_format.

Modos de response_format

Modo 1: json_schema (recomendado)

Defina a estrutura de saída com precisão usando um JSON Schema padrão. O modelo gera uma saída que segue estritamente o schema:

{
    "type": "json_schema",
    "schema": {
        "type": "object",
        "properties": {
            "field_name": {"type": "string"},
            "field_age": {"type": "integer"}
        },
        "required": ["field_name", "field_age"],
        "additionalProperties": false
    }
}

Quanto mais preciso for o schema (restrições de tipo, valores enum e descrição), maior será a qualidade da saída.

Modo 2: json_object

Garante apenas que a saída seja um objeto JSON válido. Os campos específicos são controlados pelo prompt:

{
    "type": "json_object"
}

Ao usar json_object, descreva explicitamente os campos e o formato JSON esperados no prompt da mensagem.

Exemplos

Exemplo 1: Extrair entidades estruturadas de texto

SELECT ai_gen_structured(
    model_name => 'qwen3.7-max',
    message => 'Extract personal information from the following text: Zhang San is a senior engineer at Alibaba, male, Han ethnicity, born on March 15, 1990, 35 years old this year.',
    response_format => '{
        "type": "json_schema",
        "schema": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "age": {"type": "integer"},
                "sex": {"type": "string", "enum": ["male", "female"]},
                "birth_day": {"type": ["string", "null"], "format": "date"},
                "ethnicity": {"type": "string"}
            },
            "required": ["name", "age", "sex", "birth_day", "ethnicity"],
            "additionalProperties": false
        }
    }'::json
);

Saída:

{"name": "Zhang San", "age": 35, "sex": "male", "birth_day": "1990-03-15", "ethnicity": "Han"}

Exemplo 2: Modo json_object

SELECT ai_gen_structured(
    model_name => 'qwen3.7-max',
    message => 'Return information about the city of Hangzhou in JSON format, with the fields province and is_municipality (a boolean).',
    response_format => '{"type": "json_object"}'::json
);

Saída:

{"province": "Zhejiang", "is_municipality": false}

Exemplo 3: Multimodal - extrair informações estruturadas de uma imagem

SELECT ai_gen_structured(
    model_name => 'qwen3.7-plus',
    message => 'Recognize this driving-scene image and extract structured scene information.',
    input_file => to_file(
        'oss://your-bucket/path/to/image.jpg',
        'oss-cn-hangzhou-internal.aliyuncs.com',
        'acs:ram::your_account_id:role/your_role'
    ),
    response_format => '{
        "type": "json_schema",
        "schema": {
            "type": "object",
            "properties": {
                "scene": {"type": "string", "description": "Scene description"},
                "time_of_day": {"type": "string", "enum": ["day", "night", "dusk"]},
                "weather": {"type": "string"},
                "has_vehicle": {"type": "boolean"}
            },
            "required": ["scene", "time_of_day", "weather", "has_vehicle"],
            "additionalProperties": false
        }
    }'::json
);

Exemplo 4: Processamento em lote de dados de tabela

-- Assume the documents table has id and content columns
SELECT id, ai_gen_structured(
    'qwen3.7-max',
    'Extract personal information: ' || content,
    '{"type":"json_schema","schema":{"type":"object","properties":{"name":{"type":"string"},"age":{"type":"integer"},"city":{"type":"string"}},"required":["name","age","city"],"additionalProperties":false}}'::json,
    'skip',
    '{"temperature":0.1}'::json
) AS extracted_info
FROM documents
ORDER BY id;

No processamento em lote, use on_error => 'skip' para impedir que uma única linha com falha aborte toda a consulta.

Construir um arquivo de entrada multimodal

Use a função to_file() para construir um parâmetro do tipo FILE:

to_file(
    object_uri  TEXT,   -- OSS object path, such as 'oss://bucket/path/file.jpg'
    endpoint    TEXT,   -- OSS endpoint, such as 'oss-cn-hangzhou-internal.aliyuncs.com'
    role_arn    TEXT    -- RAM role ARN, such as 'acs:ram::account_id:role/role_name'
)

A instância precisa ter autorização para ler o bucket OSS de destino por meio do ARN da função correspondente.

Notas de uso

Design de schema: A qualidade da saída aumenta proporcionalmente à precisão do JSON Schema em response_format. Adicione uma descrição a cada campo, use enum para valores de um conjunto fixo e utilize o tipo ["string", "null"] para campos opcionais.
Processamento em lote: Ao extrair dados de uma tabela em lotes, configure on_error => 'skip' ou 'capture' para evitar que uma falha em uma única linha interrompa toda a consulta.
Seleção de modelo: Para extração de texto, prefira qwen3.7-max (foco em qualidade) ou qwen3.7-plus (melhor custo-benefício). Em cenários multimodais, opte por um modelo com compreensão visual, como o qwen3.7-plus.
Saída não JSON: Caso necessite de saída de texto em formato não JSON, utilize a função ai_gen.
Parâmetro params: No modo de saída estruturada, o mecanismo substitui alguns parâmetros do modelo (como max_tokens) para garantir que a saída JSON esteja completa. Outros parâmetros, como temperature, continuam tendo efeito.