使用入门

准备工作

• 了解如何使用API调用OpenNLU开放域文本理解模型，包括请求的入参及出参。

• 获取阿里云大模型服务平台百炼的API Key。

定义模型输入与输出函数

• 模型输入函数：

  在使用HTTP调用opennlu-v1模型时，请求体的内容示例如下所示：

  {
    "model": "opennlu-v1",
    "input":{
      "sentence":"国足近5年首次攻破日本队球门！",
      "task": "classification",
      "labels":"体育新闻，娱乐新闻"
    },
    "parameters": {
    }
  }

  请求体中，参数model、input.sentence及input.labels为必填项。此外，input.task项作为模型入参，固定为classification。则模型输入函数可定义为：

  -- model, input.sentence, input.labels项为输入内容，input.task项固定
  CREATE OR REPLACE FUNCTION my_text_classification_in(model text, content text)
      RETURNS jsonb
      LANGUAGE plpgsql
      AS $function$
      BEGIN
      RETURN ('{"model": "'|| model ||'","input":{"sentence":"'|| content ||'","task": "classification","labels":"体育新闻，时事新闻"},"parameters":{}}')::jsonb;
      END;
      $function$;

• 模型输出函数：

  在使用HTTP调用opennlu-v1模型时，请求输出内容示例如下所示：

  {
      "output":{
          "text":"体育新闻",
      },
      "usage":{
          "output_tokens":2,
          "input_tokens":11,
          "total_tokens":13
      },
      "request_id":"d89c06fb-46a1-47b6-acb9-bfb17f814969"
  }

  由于仅需获取output.text项的内容，且输出为一个极为简单的词语，无需进行任何处理，因此模型输出函数无需定义。

创建文本分类模型

调用AI_CreateModel创建模型。在创建模型的过程中，需对以下参数进行调整：

• 模型调用地址model_url域名修改，将OpenNLU的HTTP调用域名的替换为阿里云大模型服务平台百炼的私网连接（PrivateLink），即将https://dashscope.aliyuncs.com更改为http://vpc-cn-beijing.dashscope.aliyuncs.com。

• 模型配置信息model_config中的token替换为您阿里云大模型服务平台百炼的API Key。

• 模型输入转换函数model_in_transform_fn为上述步骤创建的my_text_classification_in函数。

SELECT polar_ai.ai_createmodel('my_text_classification_model', 'http://vpc-cn-beijing.dashscope.aliyuncs.com/api/v1/services/nlp/nlu/understanding','Alibaba','OpenNLU开放域文本理解模型','opennlu-v1','{"author_type": "token", "token": "<YOUR_API_KEY>"}', NULL,'my_text_classification_in'::regproc,NULL);

创建模型的调用函数

根据AI_CallModel创建自定义模型调用函数：

CREATE OR REPLACE FUNCTION my_text_classification_func(model_id text, content text)
    RETURNS text
    AS $$ select (((polar_ai.AI_CALLMODEL($1,$2)::json)->>'output')::jsonb->>'text')::text as result $$
    LANGUAGE 'sql' IMMUTABLE;

通过SQL语句执行文档分类

调用上述创建的函数进行模型调用。

SELECT my_text_classification_func('my_text_classification_model', '国足近5年首次攻破日本队球门！');

返回结果如下：

体育新闻;

（可选）批量文本分类

对于已经在数据库内的数据，可以批量执行文本分类，详细步骤如下。

1. 准备测试数据。

   -- 创建表
   CREATE TABLE my_text_classification_tbl(id integer, content text, class text);
   
   -- 插入数据
   INSERT INTO my_text_classification_tbl VALUES(1,'国足近5年首次攻破日本队球门！'),(2,'中国智慧点亮全球治理的拉美时刻'),(3,'王楚钦复仇莫雷加德晋级四强');

2. 批量文本分类。

   UPDATE my_text_classification_tbl SET class=my_text_classification_func('my_text_classification_model', content);

   执行如下SQL语句查看分类结果。

   SELECT * FROM my_text_classification_tbl;

   返回结果如下：

    id |            content             |   class   
   ----+--------------------------------+-----------
     1 | 国足近5年首次攻破日本队球门！       | 体育新闻;
     2 | 中国智慧点亮全球治理的拉美时刻      | 时事新闻;
     3 | 王楚钦复仇莫雷加德晋级四强          | 体育新闻;
   (3 rows)

准备工作

• 了解如何使用API调用通用文本向量，包括请求的入参及出参。

• 获取阿里云大模型服务平台百炼的API Key。

定义模型输入与输出函数

• 在使用HTTP调用text-embedding-v2模型时，请求体的内容示例如下所示：

  {
      "model": "text-embedding-v2",
      "input": {
          "texts": [
          "风急天高猿啸哀"
          ]
      },
      "parameters": {
          "text_type": "query"
      }
  }

  请求体中，参数model和input.texts为必填项，则模型输入函数可定义为：

  CREATE OR REPLACE FUNCTION my_text_embedding_in(model text, texts text)
      RETURNS jsonb
      LANGUAGE plpgsql
      AS $function$
      BEGIN
      RETURN ('{"model": "'|| model ||'","input":{"texts":["'|| texts ||'"]},"parameters":{"text_type": "query"}}')::jsonb;
      END;
      $function$;

• 定义模型输出函数。

  在使用HTTP调用text-embedding-v2模型时，请求输出内容示例如下所示：

  {
    "usage": {
      "total_tokens": 7
    },
    "output": {
      "embeddings": [{
        "embedding": [0.004930191827757042, -0.008629344325205105, 0.041976027360927766],
        "text_index": 0
      }]
    },
    "request_id": "317ba0d4-6c08-9c24-8725-eebd445def51"
  }

  由于仅需获取output.embeddings.embedding中的向量部分内容，且保留jsonb格式，因此模型输出函数可定义为：

  CREATE OR REPLACE FUNCTION my_text_embedding_out(model_id text, response_json jsonb)
      RETURNS jsonb
      AS $$ select ((((response_json->>'output')::jsonb->>'embeddings')::jsonb)->0->>'embedding')::jsonb as result $$
      LANGUAGE 'sql' IMMUTABLE;

创建文本向量模型

调用AI_CreateModel创建模型。在创建模型的过程中，需对以下参数进行调整：

• 模型调用地址model_url域名修改，将通用文本向量的HTTP调用域名的替换为阿里云大模型服务平台百炼的私网连接（PrivateLink），即将https://dashscope.aliyuncs.com更改为http://vpc-cn-beijing.dashscope.aliyuncs.com。

• 模型配置信息model_config中的token替换为您阿里云大模型服务平台百炼的API Key。

• 模型输入转换函数model_in_transform_fn为上述步骤创建的my_text_embedding_in函数。

• 模型输出转换函数model_out_transform_fn为上述步骤创建的my_text_embedding_out函数。

SELECT polar_ai.ai_createmodel('my_text_embedding_model', 'http://vpc-cn-beijing.dashscope.aliyuncs.com/api/v1/services/embeddings/text-embedding/text-embedding','Alibaba','通用文本向量模型','text-embedding-v2','{"author_type": "token", "token": "<YOUR_API_KEY>"}', NULL, 'my_text_embedding_in'::regproc, 'my_text_embedding_out'::regproc);

创建模型的调用函数

根据AI_CallModel创建自定义模型调用函数：

CREATE OR REPLACE FUNCTION my_text_embedding_func(model_id text, texts text)
    RETURNS float8[]
    AS $$ select array(select json_array_elements_text(polar_ai.AI_CALLMODEL($1,$2)::json))::float8[] as result $$
    LANGUAGE 'sql' IMMUTABLE;

批量文本转向量

对于已经在数据库内的数据，可以批量执行文本转向量并写入向量字段。详细步骤如下：

1. 创建向量插件。

   CREATE EXTENSION vector;

2. 创建向量表并插入数据。

   CREATE TABLE my_text_embedding_tbl(id int, content text, vec vector(1536));
   INSERT INTO my_text_embedding_tbl VALUES(1,'PolarDB是阿里巴巴自研的新一代云原生数据库，在存储计算分离架构下，利用了软硬件结合的优势，为用户提供具备秒级弹性、高性能、海量存储、安全可靠的数据库服务。'),(2,'postgresql是一种开源的关系型数据库管理系统，由PostgreSQL Global Development Group开发，由Perl编写。');

3. 批量执行文本转向量并写入表。

   UPDATE my_text_embedding_tbl set vec=my_text_embedding_func('my_text_embedding_model', content);

向量检索

将文本转成向量后，可利用PGVector（向量检索）进行快速、准确地检索相似文本。

1. （可选）创建向量插件。

   说明

   若您在上述步骤已创建向量插件，请忽略当前步骤。

   CREATE EXTENSION vector;

2. 创建向量索引。

   CREATE INDEX ON my_text_embedding_tbl USING hnsw (vec vector_l2_ops);

3. 根据内容进行检索。

   SELECT content FROM my_text_embedding_tbl WHERE vec <=> my_text_embedding_func('my_text_embedding_model', 'PolarDB数据库架构是怎么样的？')::vector(1536) < 0.5;

   返回结果如下：

   PolarDB是阿里巴巴自研的新一代云原生数据库，在存储计算分离架构下，利用了软硬件结合的优势，为用户提供具备秒级弹性、高性能、海量存储、安全可靠的数据库服务。