Google Cloud Vertex.AI API 访问

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

以下所有过程都可以具有以下 APOC 配置，即在 apoc.conf 中或通过 docker 环境变量 .Apoc 配置

键

描述

默认值

apoc.ml.vertexai.url

OpenAI 端点基本 URL

endpoint 配置参数的值

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

表 1. 常用配置参数
键	描述	默认值
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, 即第二个参数> }`
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} 由第三个参数 (project) 定义
{resource} 由 resource 配置定义

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

让我们看一些例子。

生成嵌入 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. 生成嵌入响应
索引	文本	嵌入
0	"Some Text"	[-0.0065358975, -7.9563365E-4, …. -0.010693862, -0.005087272]

表 3. 参数
名称	描述
texts	文本字符串列表
accessToken	Vertex.AI API 访问令牌
project	Google Cloud 项目
configuration	用于模型和其他请求参数（如`region`）的可选映射

表 4. 结果
名称	描述
索引	原始列表中的索引条目
文本	原始列表中的文本行
嵌入	textembedding-gecko 模型的 768 个元素浮点嵌入向量

文本补全 API

此过程apoc.ml.vertexai.completion可以继续/完成给定的文本。

它使用补全模型 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. 参数
名称	描述
prompt	要补全的文本
accessToken	Vertex.AI API 访问令牌
project	Google Cloud 项目
configuration	用于模型、区域、温度、topK、topP、maxOutputTokens 和其他请求参数的可选映射

表 6. 结果
名称	描述
值	来自 Vertex.AI 的结果条目（内容、safetyAttributes(blocked, categories, scores)、recitationResult(recitationAction, recitations)）

聊天补全 API

此过程apoc.ml.vertexai.chat接收助理和用户之间聊天交换的映射列表（包含可选的系统上下文），并返回流中的下一条消息。

它使用聊天模型 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. 参数
名称	描述
messages	包含 `{author:"bot
user", content:"text"}` 指令的映射列表	accessToken
Vertex.AI API 访问令牌	project
Google Cloud 项目	configuration
用于区域、模型、温度、topK、topP、maxOutputTokens 和其他参数的可选映射	context
补全的可选上下文和系统提示	examples

表 8. 结果
名称	描述
值	来自 Vertex.AI 的结果条目（包含 candidates(author, content)、safetyAttributes(categories, scores, blocked)、recitationResults(recitationAction, recitations)）

流式 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: " This is a photo of a book…"}]}, 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"}]}]}]`

此外，我们还可以与其他 Google API 一起使用，这些 API 的端点不以https://<region>-aiplatform.googleapis.com开头，例如，我们可以使用文本转语音 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"})