谷歌云 Vertex.AI API 访问

您需要在您的账户中创建一个 Google Cloud 项目并启用 Vertex.AI 服务。作为访问令牌，您可以运行 gcloud auth print-access-token。使用这些服务将会在您的 Google Cloud 账户中产生费用。

以下所有过程均可使用如下 APOC 配置，例如在 apoc.conf 中或通过 docker 环境变量配置。Apoc 配置

键 (key)

description（描述）

默认

apoc.ml.vertexai.url

OpenAI 端点基础 URL

endpoint 配置参数值

此外，它们可以包含以下配置键，作为最后一个参数。

表 1. 通用配置参数
键 (key)	description（描述）	默认
endpoint	类似于 `apoc.ml.vertexai.url` APOC 配置	https://{region}-aiplatform.googleapis.com/v1/projects/{project}/locations/{region}/publishers/google/models/{model}:{resource}
headers	用于添加或编辑 HTTP 默认标头	`{Content-Type: "application/json", Accept: "application/json", Authorization: "Bearer " + <$accessToken, 即第 2 个参数> }`
model	Vertex AI 模型	取决于具体过程
region	Vertex AI 区域	us-central1
resource（资源）	Vertex AI 资源（见下文）	取决于具体过程
temperature, maxOutputTokens, maxDecodeSteps, topP, topK	可以传递到 HTTP 请求中的可选参数。取决于所使用的 API	{temperature: 0.3, maxOutputTokens: 256, maxDecodeSteps: 200, topP: 0.8, topK: 40}

我们可以将 endpoint 配置定义为完整 URL，例如 https://us-central1-aiplatform.googleapis.com/v1/projects/myVertexAIProject/locations/us-central1/publishers/google/models/gemini-pro-vision:streamGenerateContent，或者通过会被其他配置替换的参数来定义它。

例如，如果我们不定义 endpoint 配置，则将采用默认值 https://{region}-aiplatform.googleapis.com/v1/projects/{project}/locations/{region}/publishers/google/models/{model}:{resource}，其中

{model} 将是由 model 配置定义的模型
{region} 由 region 配置定义
{project} 由第 3 个参数 (project) 定义
{resource} 由 resource 配置定义

或者，我们可以将 endpoint 定义为 https://us-central1-aiplatform.googleapis.com/v1/projects/{project}/locations/us-central1/publishers/google/models/gemini-pro-vision:streamGenerateContent，在这种情况下，我们只需将 {project} 替换为第 3 个参数。

让我们看一些例子。

生成嵌入 API (Generate Embeddings API)

此过程 apoc.ml.vertexai.embedding 可以接受文本字符串列表，并将为每个字符串返回一行，嵌入数据作为一个 768 元素的向量。它使用嵌入端点，该端点在此处有文档说明。

API 配额是按项目/按区域计算的，您可以在配置映射中覆盖默认的 us-central1，例如 {region:'us-east4'}。GCP 区域可以在此处找到：https://cloud.google.com/about/locations

附加配置被传递给 API，默认使用的模型是 textembedding-gecko。

生成嵌入调用

CALL apoc.ml.vertexai.embedding(['Some Text'], $accessToken, $project, {region:'<region>'}) yield index, text, embedding;

表 2. 生成嵌入响应
index	文本 (text)	embedding
0	"一些文本"	[-0.0065358975, -7.9563365E-4, …. -0.010693862, -0.005087272]

表 3. 参数
名称 (name)	description（描述）
texts	文本字符串列表
accessToken	Vertex.AI API 访问令牌
project	Google Cloud 项目
配置	用于 model 等条目以及 region 等其他请求参数的可选映射

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

文本补全 API (Text Completion API)

此过程 apoc.ml.vertexai.completion 可以延续/补全给定的文本。

它使用补全模型 API，该 API在此处有文档说明。

附加配置被传递给 API，默认使用的模型是 text-bison。

文本补全调用

CALL apoc.ml.vertexai.completion('What color is the sky? Answer in one word: ', $apiKey, $project, {})

文本补全响应

{value={safetyAttributes={blocked=false, scores=[0.1], categories=[Sexual]},
recitationResult={recitations=[], recitationAction=NO_ACTION}, content=blue}}

表 5. 参数
名称 (name)	description（描述）
prompt	要补全的文本
accessToken	Vertex.AI API 访问令牌
project	Google Cloud 项目
配置	用于 model, region, temperature, topK, topP, maxOutputTokens 以及其他请求参数的可选映射

表 6. 结果
名称 (name)	description（描述）
值	来自 Vertex.AI 的结果条目（内容，安全属性(blocked, categories, scores)，朗读结果(recitationAction, recitations)）

聊天补全 API (Chat Completion API)

此过程 apoc.ml.vertexai.chat 接受助理和用户之间聊天记录的映射列表（带有可选的系统上下文），并将返回流程中的下一条消息。

它使用聊天模型 API，该 API在此处有文档说明。

附加配置被传递给 API，默认使用的模型是 chat-bison。

聊天补全调用

CALL apoc.ml.vertexai.chat(
/*messages*/
[{author:"user", content:"What planet do timelords live on?"}],
$apiKey, $project,
{temperature:0},
/*context*/ "Fictional universe of Doctor Who. Only answer with a single word!",
/*examples*/ [{input:{content:"What planet do humans live on?"}, output:{content:"Earth"}}])
yield value

聊天补全响应

{value={candidates=[{author=1, content=Gallifrey.}], safetyAttributes={blocked=false, scores=[0.1, 0.1, 0.1], categories=[Religion & Belief, Sexual, Toxic]}, recitationResults=[{recitations=[], recitationAction=NO_ACTION}]}}

表 7. 参数
名称 (name)	description（描述）
messages	指令映射列表，格式为 `{author:"bot\|user", content:"text"}`
accessToken	Vertex.AI API 访问令牌
project	Google Cloud 项目
配置	用于 region, model, temperature, topK, topP, maxOutputTokens 以及其他参数的可选映射
上下文 (context)	用于补全的可选上下文和系统提示
examples	可选示例列表：`[{input:{content:"input text"},output:{content:"expected output text"}]`

表 8. 结果
名称 (name)	description（描述）
值	来自 Vertex.AI 的结果条目（包含候选者(author, content)，安全属性(categories, scores, blocked)，朗读结果(recitationAction, recitations)）

流式 API (Streaming API)

此过程 apoc.ml.vertexai.stream 接受助理和用户之间内容交换的映射列表（带有可选的系统上下文），并将返回流程中的下一条消息。

默认情况下，它使用 Gemini AI API。

CALL apoc.ml.vertexai.stream([{role: "user", parts: [{text: "translate book in italian"}]}], '<accessToken>', '<projectID>')

表 9. 结果
值
`{finishReason:"STOP", safetyRatings:[{probability:"NEGLIGIBLE", category:"HARM_CATEGORY_HARASSMENT"}, {probability:"NEGLIGIBLE", category:"HARM_CATEGORY_HATE_SPEECH"}, {probability:"NEGLIGIBLE", category:"HARM_CATEGORY_SEXUALLY_EXPLICIT"}, {probability:"NEGLIGIBLE", category:"HARM_CATEGORY_DANGEROUS_CONTENT"}], content:{role:"model", parts:[{text:"Libro"}]}}`

我们可以调整参数，例如 temperature

CALL apoc.ml.vertexai.stream([{role: "user", parts: [{text: "translate book in italian"}]}], '<accessToken>', '<projectID>',
    {temperature: 0})

这对应于以下 HTTP 正文请求，其中 maxOutputTokens, topP 和 topK 具有上述指定的默认值（通用配置参数）

{
    "contents": [
        {
            "role": "user",
            "parts": [
                {
                    "text": "translate book in italian"
                }
            ]
        }
    ],
    "generation_config": {
        "temperature": 0,
        "maxOutputTokens": 256,
        "topP": 0.8,
        "topK": 40
    }
}

自定义 API

使用此过程，我们可以潜在地调用 Vertex AI 提供的任何 API。

为了实现最大灵活性，在这种情况下，第一个参数不会被修改，并且与 HTTP 请求的正文完全匹配，返回类型为 ANY。

Gemini Pro Vision 示例

CALL apoc.ml.vertexai.custom({
    contents: [
        {
            role: "user",
            parts: [
					{text: "What is this?"},
                    {inlineData: {
                        mimeType: "image/png",
                        data: '<base64Image>'}
                }
            ]
        }
    ]
},
"<accessToken>",
"<projectId>",
{model: 'gemini-pro-vision'}
)

表 10. 结果
值
[{usageMetadata: {promptTokenCount: 262, totalTokenCount: 272, candidatesTokenCount: 10}, candidates: [{content: {role: "model", parts: [{text: " 这是一张书的照片……"}]}, finishReason: "STOP", safetyRatings: [{category: "HARM_CATEGORY_HARASSMENT", probability: "NEGLIGIBLE"}, {category: "HARM_CATEGORY_HATE_SPEECH", probability: "NEGLIGIBLE"}, {category: "HARM_CATEGORY_SEXUALLY_EXPLICIT", probability: "NEGLIGIBLE"}, {category: "HARM_CATEGORY_DANGEROUS_CONTENT", probability: "NEGLIGIBLE"}]}]}]

CALL apoc.ml.vertexai.custom({contents: {role: "user", parts: [{text: "translate book in italian"}]}},
    "<accessToken>",
    "<projectId>",
    {endpoint: "https://us-central1-aiplatform.googleapis.com/v1/projects/{project}/locations/us-central1/publishers/google/models/gemini-pro-vision:streamGenerateContent"}
)

表 11. 结果
值
`[{usageMetadata: {promptTokenCount: 4, totalTokenCount: 5, candidatesTokenCount: 1}, candidates: [{content: {role: "model", parts: [{text: "libro"}]}, finishReason: "STOP", safetyRatings: [{category: "HARM_CATEGORY_HARASSMENT", probability: "NEGLIGIBLE"}, {category: "HARM_CATEGORY_HATE_SPEECH", probability: "NEGLIGIBLE"}, {category: "HARM_CATEGORY_SEXUALLY_EXPLICIT", probability: "NEGLIGIBLE"}, {category: "HARM_CATEGORY_DANGEROUS_CONTENT", probability: "NEGLIGIBLE"}]}]}]`

CALL apoc.ml.vertexai.custom({contents: {role: "user", parts: [{text: "translate book in italian"}]}},
    "<accessToken>",
    null,
    {endpoint: "https://us-central1-aiplatform.googleapis.com/v1/projects/vertex-project-413513/locations/us-central1/publishers/google/models/gemini-pro-vision:streamGenerateContent"}
)

表 12. 结果
值
`[{usageMetadata: {promptTokenCount: 4, totalTokenCount: 5, candidatesTokenCount: 1}, candidates: [{content: {role: "model", parts: [{text: "libro"}]}, finishReason: "STOP", safetyRatings: [{category: "HARM_CATEGORY_HARASSMENT", probability: "NEGLIGIBLE"}, {category: "HARM_CATEGORY_HATE_SPEECH", probability: "NEGLIGIBLE"}, {category: "HARM_CATEGORY_SEXUALLY_EXPLICIT", probability: "NEGLIGIBLE"}, {category: "HARM_CATEGORY_DANGEROUS_CONTENT", probability: "NEGLIGIBLE"}]}]}]`

Gemini Flash 示例

CALL apoc.ml.vertexai.custom({
  "contents": [
    { "parts": [
        {
            "text": "translate the word 'book' in italian"
        }],
        "role": "user"
    }]
},
"<accessToken>",
"<projectId>",
{model: 'gemini-1.5-flash-001'}
)

表 13. 结果
值
{ "candidates" : [ { "finishReason" : "STOP", "safetyRatings" : [ { "severity" : "HARM_SEVERITY_NEGLIGIBLE", "probabilityScore" : 0.09484524, "category" : "HARM_CATEGORY_HATE_SPEECH", "severityScore" : 0.08882029, "probability" : "NEGLIGIBLE" }, { "severity" : "HARM_SEVERITY_NEGLIGIBLE", "probabilityScore" : 0.041307304, "category" : "HARM_CATEGORY_DANGEROUS_CONTENT", "severityScore" : 0.10687688, "probability" : "NEGLIGIBLE" }, { "severity" : "HARM_SEVERITY_NEGLIGIBLE", "probabilityScore" : 0.12808825, "category" : "HARM_CATEGORY_HARASSMENT", "severityScore" : 0.047691282, "probability" : "NEGLIGIBLE" }, { "severity" : "HARM_SEVERITY_NEGLIGIBLE", "probabilityScore" : 0.100348406, "category" : "HARM_CATEGORY_SEXUALLY_EXPLICIT", "severityScore" : 0.10800066, "probability" : "NEGLIGIBLE" } ], "content" : { "parts" : [ { "text" : "意大利语中“书”是 libro。 \n" } ], "role" : "model" } } ], "usageMetadata" : { "totalTokenCount" : 21, "candidatesTokenCount" : 13, "promptTokenCount" : 8 } }

此外，我们可以将其他 Google API 与端点不以 https://<region>-aiplatform.googleapis.com 开头的 API 一起使用，例如我们可以使用 Text-to-Speech API

CALL apoc.ml.vertexai.custom(
{
  input:{
    text:'just a test'
  },
  voice:{
    languageCode:'en-US',
    name:'en-US-Studio-O'
  },
  audioConfig:{
    audioEncoding:'LINEAR16',
    speakingRate:1
  }
},
"<accessToken>",
"<projectId>",
{endpoint: "https://texttospeech.googleapis.com/v1/text:synthesize"})