Watson API 访问

您需要获取一个 Watson bearer access token 才能使用这些过程。此令牌必须在第二个参数中定义。

每个过程可以有以下 APOC 配置参数，例如在 apoc.conf 中或通过 docker 环境变量

表 1. Apoc 配置
键	描述	默认值
apoc.ml.watson.project.id	project_id	配置映射中定义的 `project_id`
apoc.ml.watson.url	REST API 端点	https://eu-de.ml.cloud.ibm.com/ml/v1-beta/generation/text?version=2023-05-29

我们可以直接将请求体放入配置参数中，但“input”键除外，该键将通过过程的第一个参数添加，稍后我们将看到。

例如，如果我们要发送此请求

{
 "model_id": "google/flan-ul2",
 "input": "my test input",
 "parameters": {
  "max_new_tokens": 3
 },
 "project_id": "MyProjectId"
}

我们可以创建以下配置映射

{
    model_id: "google/flan-ul2",
    project_id: "MyProjectId",
    parameters: {
      max_new_tokens: 3
    }
}

请注意，model_id 不是强制性的，因为它有一个默认值 "ibm/granite-13b-chat-v2"

同样 project_id 也不是强制性的，如果它已经通过 APOC 配置定义，或者如果在配置映射中存在一个键为 space_id 或 wml_instance_crn 的条目；否则，将抛出错误，因为 Watson 请求 API 需要其中之一。

此外，我们可以在配置映射中放置条目 endpoint: "ENDPOINT_URL"，它定义了 REST API 端点，并优先于 apoc.watson.url APOC 配置。如果两者都没有指定，将使用默认值 "https://eu-de.ml.cloud.ibm.com/ml/v1-beta/generation/text?version=2023-05-29"。

以下示例假设我们有此 apoc.conf

apoc.watson.project.id=MY_PROJECT_ID

文本补全 API

这个过程 apoc.ml.watson.completion 可以继续/补全给定的文本。

以下过程将在没有任何配置的情况下创建以下 API 请求

{
"model_id": "ibm/granite-13b-chat-v2",
"input": "What color is the sky? Answer in one word: ,
"project_id": "<the one explicited in the APOC config>"
}

文本补全调用

CALL apoc.ml.watson.completion('What color is the sky? Answer in one word: ', '<apiKey>', {})

结果如下

表 2. 文本补全响应示例
值
{"model_id": "ibm/granite-13b-chat-v2", "created_at": "2024-01-11T09:33:46.130Z", "results": [ { "generated_text": "\nThe sky is blue.", "generated_token_count": 7, "input_token_count": 12, "stop_reason": "eos_tokens" } ] }

聊天补全 API

这个过程 apoc.ml.watson.chat 接受一个聊天消息的映射列表，并将返回流程中的下一条消息。

必须指定 role 和 content 键。

从 messages 列表将创建一个字符串，如 : \n : 等等...。

例如，以下调用将创建一个带有此请求体的请求

{
 "model_id": "ibm/granite-13b-chat-v2",
 "input": "system: Only answer with a single word\nuser: What planet do humans live on?",
 "project_id": "<the one explicited in the APOC config>"
}

聊天补全调用

CALL apoc.ml.watson.chat([
    {role:"system", content:"Only answer with a single word"},
    {role:"user", content:"What planet do humans live on?"}
],  $apiKey) yield value

结果如下

表 3. 聊天补全响应示例
值
{"model_id": "ibm/granite-13b-chat-v2", "created_at": "2024-01-11T09:33:46.130Z", "results": [ { "generated_text": " system: Earth", "generated_token_count": 7, "input_token_count": 12, "stop_reason": "eos_tokens" } ] }

生成嵌入 API

这个过程 apoc.ml.watson.embedding 可以接受一个文本字符串列表，并为每个字符串返回一行，其中包含作为 512 元素向量的嵌入数据。

附加配置被传递给 API，使用的默认模型是 ibm/slate-30m-english-rtrvr。请参阅此处查看当前模型的列表。

生成嵌入调用

CALL apoc.ml.watson.embedding(['Some Text'], $accessToken, $project, {}) yield index, text, embedding;

表 4. 生成嵌入响应
索引	文本	嵌入
0	"Some Text"	[-0.0065358975, -7.9563365E-4, …. -0.010693862, -0.005087272]

表 5. 参数
名称	描述
文本列表	文本字符串列表
accessToken	Watson 访问令牌
configuration	可选配置映射，与其他过程等效

表 6. 结果
名称	描述
索引	原始列表中的索引条目
文本	原始列表中的文本行
嵌入	ada-002 模型的浮点嵌入向量