Watson API 访问

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

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

表 1. APOC 配置
键 (key)	description（描述）	默认
apoc.ml.watson.project.id	项目 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"

此外，如果已通过 APOC 配置定义，或者配置映射中包含键为 space_id 或 wml_instance_crn 的条目，则 project_id 也不是强制性的；否则将抛出错误，因为 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 (Text Completion 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 (Chat Completion API)

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

必须指定键 role 和 content。

根据 messages 列表，将创建一个类似于 <roleValue1>: <contentValue1> \n <roleValue2>: <contentValue2> 等... 的字符串。

例如，以下调用将创建具有此主体的请求

{
 "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 (Generate Embeddings 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. 生成嵌入响应
index	文本 (text)	embedding
0	"一些文本"	[-0.0065358975, -7.9563365E-4, …. -0.010693862, -0.005087272]

表 5. 参数
名称 (name)	description（描述）
texts	文本字符串列表
accessToken	Watson 访问令牌
配置	可选配置映射，与其他过程相同

表 6. 结果
名称 (name)	description（描述）
index	原始列表中的索引条目
文本 (text)	原始列表中的文本行
embedding	用于 ada-002 模型的浮点嵌入向量