教程：Gemini API 使用入门

<ph type="x-smartling-placeholder"></ph>


本教程演示了如何访问 Node.js 版 Gemini API 使用 Google AI JavaScript SDK。

在本教程中，您将了解如何执行以下操作：

此外，本教程还包含一些有关高级用例（如 embeddings 和 计算词元）以及 控制内容生成。

前提条件

本教程假定您熟悉如何使用 Node.js。

要完成本教程，请确保您的开发环境符合 以下要求：

  • Node.js v18 及更高版本
  • npm

设置项目

在调用 Gemini API 之前，您需要设置项目，包括 设置 API 密钥、安装 SDK 软件包并初始化模型。

设置您的 API 密钥

如需使用 Gemini API，您需要 API 密钥。如果您还没有账号， 在 Google AI Studio 中创建密钥。

获取 API 密钥

保护您的 API 密钥

强烈建议您不要将 API 密钥签入您的版本 控制系统相反，您应该为 API 密钥使用 Secret 存储区。

本教程中的所有代码段均假定您以 环境变量

安装 SDK 软件包

如需在您自己的应用中使用 Gemini API，您需要安装 适用于 Node.js 的 GoogleGenerativeAI 软件包：

npm install @google/generative-ai

初始化生成模型

在进行任何 API 调用之前，您需要先导入并初始化 生成模型。

const { GoogleGenerativeAI } = require("@google/generative-ai");

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

// ...

// The Gemini 1.5 models are versatile and work with most use cases
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash"});

// ...

指定模型时，请注意以下事项：

  • 请使用您的用例专用的模型（例如 gemini-1.5-flash 适用于多模态输入）。在本指南中， 实现列出了每个用例的推荐模型。

实现常见使用场景

现在您的项目已设置完毕，您可以探索如何使用 Gemini API 来 实现不同的应用场景：

在“高级用例”部分，您可以找到有关 Gemini API 的信息 和嵌入。

根据纯文本输入生成文本

当提示输入仅包含文本时，使用带有 generateContent 的 Gemini 1.5 模型生成文本输出：

const { GoogleGenerativeAI } = require("@google/generative-ai");

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

async function run() {
  // The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
  const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash"});

  const prompt = "Write a story about a magic backpack."

  const result = await model.generateContent(prompt);
  const response = await result.response;
  const text = response.text();
  console.log(text);
}

run();

根据文本和图片输入生成文本（多模态）

Gemini 1.5 Flash 和 1.5 Pro 可以处理多模态输入，以便同时输入两种文本 和图片。请务必查看 提示的图片要求。

如果输入的提示同时包含文本和图片，请使用符合以下条件的 Gemini 1.5 模型： generateContent 方法，用于生成文本输出：

const { GoogleGenerativeAI } = require("@google/generative-ai");
const fs = require("fs");

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

// Converts local file information to a GoogleGenerativeAI.Part object.
function fileToGenerativePart(path, mimeType) {
  return {
    inlineData: {
      data: Buffer.from(fs.readFileSync(path)).toString("base64"),
      mimeType
    },
  };
}

async function run() {
  // The Gemini 1.5 models are versatile and work with both text-only and multimodal prompts
  const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash" });

  const prompt = "What's different between these pictures?";

  const imageParts = [
    fileToGenerativePart("image1.png", "image/png"),
    fileToGenerativePart("image2.jpeg", "image/jpeg"),
  ];

  const result = await model.generateContent([prompt, ...imageParts]);
  const response = await result.response;
  const text = response.text();
  console.log(text);
}

run();

建立多轮对话（聊天）

借助 Gemini，您可以跨多个回合构建自由形式的对话。通过 SDK 通过管理对话状态来简化流程， 使用 generateContent，则无需存储对话记录 。

如需构建多轮对话（如聊天），请使用 Gemini 1.5 模型或 Gemini 1.0 Pro 模型，并通过调用 startChat() 来初始化对话。 然后，使用 sendMessage() 发送一条新的用户消息，此消息还将附加 消息和对聊天记录的响应。

与内容关联的 role 有两种可能的选项 对话：

  • user：提供提示的角色。该值是 sendMessage 次通话。

  • model：提供响应的角色。此角色可以在以下情况下使用： 使用现有的 history 调用 startChat()。

。 
const { GoogleGenerativeAI } = require("@google/generative-ai");

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

async function run() {
  // The Gemini 1.5 models are versatile and work with multi-turn conversations (like chat)
  const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash"});

  const chat = model.startChat({
    history: [
      {
        role: "user",
        parts: [{ text: "Hello, I have 2 dogs in my house." }],
      },
      {
        role: "model",
        parts: [{ text: "Great to meet you. What would you like to know?" }],
      },
    ],
    generationConfig: {
      maxOutputTokens: 100,
    },
  });

  const msg = "How many paws are in my house?";

  const result = await chat.sendMessage(msg);
  const response = await result.response;
  const text = response.text();
  console.log(text);
}

run();

使用流式传输加快互动速度

默认情况下，模型会在完成整个生成过程后返回响应 过程。您无需等待整个会话，即可实现更快速的互动 结果，而改用流式传输来处理部分结果。

以下示例展示了如何使用 generateContentStream 方法，用于根据文本和图片输入生成文本 提示。

//...

const result = await model.generateContentStream([prompt, ...imageParts]);

let text = '';
for await (const chunk of result.stream) {
  const chunkText = chunk.text();
  console.log(chunkText);
  text += chunkText;
}

//...

对于纯文本输入和聊天用例，您可以使用类似的方法。

// Use streaming with text-only input
const result = await model.generateContentStream(prompt);

请参阅上面的聊天示例，了解如何实例化 一个 chat。

// Use streaming with multi-turn conversations (like chat)
const result = await chat.sendMessageStream(msg);

实现高级用例

本教程上一部分中介绍的常见用例有助于 能够熟练使用 Gemini API。本部分介绍了一些 可能被视为更高级的用例。

使用嵌入

嵌入是一种用于表示信息的技术 数组中的浮点数列表。借助 Gemini，你可以 以矢量化形式处理文本（字词、句子和文本块）， 更容易比较和对比嵌入。例如， 相似的主题或情感都应具有相似的嵌入， 通过余弦相似度等数学比较技术确定的类别。

结合使用 embedding-001 模型和 embedContent 方法（或 batchEmbedContent 方法）以生成嵌入。以下示例 为单个字符串生成嵌入：

const { GoogleGenerativeAI } = require("@google/generative-ai");

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

async function run() {
  // For embeddings, use the embedding-001 model
  const model = genAI.getGenerativeModel({ model: "embedding-001"});

  const text = "The quick brown fox jumps over the lazy dog."

  const result = await model.embedContent(text);
  const embedding = result.embedding;
  console.log(embedding.values);
}

run();

调用函数

函数调用可让您更轻松地从 Google Cloud 控制台获取结构化数据输出 生成模型。然后，您可以使用这些输出来调用其他 API 并返回 将相关的响应数据提供给模型。换句话说，函数调用有助于 将生成模型连接到外部系统， 可提供最新、最准确的信息。 如需了解详情，请参阅 函数调用教程。

计算词元数量

在使用长提示时，在发送任何词元之前计算词元数量可能会有帮助 传递给模型。以下示例展示了如何使用 countTokens() 例如：

// For text-only input
const { totalTokens } = await model.countTokens(prompt);

// For text-and-image input (multimodal)
const { totalTokens } = await model.countTokens([prompt, ...imageParts]);

// For multi-turn conversations (like chat)
const history = await chat.getHistory();
const msgContent = { role: "user", parts: [{ text: msg }] };
const contents = [...history, msgContent];
const { totalTokens } = await model.countTokens({ contents });

用于控制内容生成的选项

您可以通过配置模型参数和使用 安全设置。

请注意，将 generationConfig 或 safetySettings 传递给模型请求 方法（例如 generateContent）将完全替换配置对象 在 getGenerativeModel 中传递的相同名称。

配置模型参数

您发送到模型的每个提示都包含参数值，用于控制 模型生成回答。对于不同的参数值，模型会生成不同的结果。详细了解 模型参数。

const generationConfig = {
  stopSequences: ["red"],
  maxOutputTokens: 200,
  temperature: 0.9,
  topP: 0.1,
  topK: 16,
};

// The Gemini 1.5 models are versatile and work with most use cases
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash",  generationConfig });

使用安全设置

你可以使用安全设置来调整收到符合以下要求的回答的可能性 可能会被视为有害的内容。默认情况下，安全设置会屏蔽带有“中等”标记的内容 和/或在所有维度上都属于不安全的内容的高概率。了解 详细了解安全设置。

设置一项安全设置的方法如下：

import { HarmBlockThreshold, HarmCategory } from "@google/generative-ai";

// ...

const safetySettings = [
  {
    category: HarmCategory.HARM_CATEGORY_HARASSMENT,
    threshold: HarmBlockThreshold.BLOCK_ONLY_HIGH,
  },
];

// The Gemini 1.5 models are versatile and work with most use cases
const model = genAI.getGenerativeModel({ model: "gemini-1.5-flash", safetySettings });

您还可以设定多项安全设置：

const safetySettings = [
  {
    category: HarmCategory.HARM_CATEGORY_HARASSMENT,
    threshold: HarmBlockThreshold.BLOCK_ONLY_HIGH,
  },
  {
    category: HarmCategory.HARM_CATEGORY_HATE_SPEECH,
    threshold: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE,
  },
];

后续步骤

  • 提示设计是创建提示以从语言模型引出所需回复的过程。撰写结构合理的提示是 是确保语言模型做出准确、高质量响应的一部分。 了解提示撰写的最佳做法。

  • Gemini 提供多种模型变体，以满足不同使用情形的需求 例如输入类型和复杂性、聊天或其他 对话框语言任务和大小限制。 不妨了解可用的 Gemini 模型。

。