Руководство: Начало работы с Gemini API


В этом руководстве показано, как получить доступ к API Gemini непосредственно из вашего веб-приложения с помощью Google AI JavaScript SDK. Вы можете использовать этот SDK, если не хотите напрямую работать с REST API или серверным кодом (например, Node.js) для доступа к моделям Gemini в вашем веб-приложении.

В этом уроке вы узнаете, как сделать следующее:

Кроме того, это руководство содержит разделы, посвященные расширенным вариантам использования (например, подсчету токенов ), а также параметрам управления генерацией контента .

Предварительные условия

В этом руководстве предполагается, что вы знакомы с использованием JavaScript для разработки веб-приложений. Это руководство не зависит от платформы.

Чтобы завершить работу с этим руководством, убедитесь, что ваша среда разработки соответствует следующим требованиям:

  • (Необязательно) Node.js
  • Современный веб-браузер

Настройте свой проект

Прежде чем вызывать API Gemini, вам необходимо настроить проект, включая получение ключа API, импорт SDK и инициализацию модели.

Настройте свой ключ API

Чтобы использовать API Gemini, вам понадобится ключ API. Если у вас его еще нет, создайте ключ в Google AI Studio.

Получить ключ API

Защитите свой ключ API

Настоятельно рекомендуется не проверять ключ API в вашей системе контроля версий. Вместо этого вам следует передать ключ API в свое приложение непосредственно перед инициализацией модели.

Во всех фрагментах этого руководства предполагается, что вы обращаетесь к своему ключу API как к глобальной константе.

Импортируйте SDK и инициализируйте генеративную модель.

Прежде чем вы сможете выполнять какие-либо вызовы API, вам необходимо импортировать SDK и инициализировать генеративную модель.

<html>
  <body>
    <!-- ... Your HTML and CSS -->

    <script type="importmap">
      {
        "imports": {
          "@google/generative-ai": "https://esm.run/@google/generative-ai"
        }
      }
    </script>
    <script type="module">
      import { GoogleGenerativeAI } from "@google/generative-ai";

      // Fetch your API_KEY
      const API_KEY = "...";
      // Reminder: This should only be for local testing

      // Access your API key (see "Set up your API key" above)
      const genAI = new GoogleGenerativeAI(API_KEY);

      // ...

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

      // ...
    </script>
  </body>
</html>

При указании модели обратите внимание на следующее:

  • Используйте модель, соответствующую вашему варианту использования (например, gemini-1.5-flash предназначена для мультимодального ввода). В этом руководстве в инструкциях для каждой реализации перечислена рекомендуемая модель для каждого варианта использования.

Реализация распространенных случаев использования

Теперь, когда ваш проект настроен, вы можете изучить использование Gemini API для реализации различных вариантов использования:

Генерировать текст из текстового ввода

Если ввод приглашения включает только текст, используйте модель Gemini 1.5 или модель Gemini 1.0 Pro с generateContent для создания текстового вывода:

import { GoogleGenerativeAI } from "@google/generative-ai";

// Access your API key (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(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 предоставляет различные модели, поддерживающие мультимодальный ввод (модели Gemini 1.5), так что вы можете вводить как текст, так и изображения. Обязательно ознакомьтесь с требованиями к изображениям для подсказок .

Если входные данные приглашения включают в себя как текст, так и изображения, используйте модель Gemini 1.5 с generateContent для создания текстового вывода:

import { GoogleGenerativeAI } from "@google/generative-ai";

// Access your API key (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(API_KEY);

// Converts a File object to a GoogleGenerativeAI.Part object.
async function fileToGenerativePart(file) {
  const base64EncodedDataPromise = new Promise((resolve) => {
    const reader = new FileReader();
    reader.onloadend = () => resolve(reader.result.split(',')[1]);
    reader.readAsDataURL(file);
  });
  return {
    inlineData: { data: await base64EncodedDataPromise, mimeType: file.type },
  };
}

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 fileInputEl = document.querySelector("input[type=file]");
  const imageParts = await Promise.all(
    [...fileInputEl.files].map(fileToGenerativePart)
  );

  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 : роль, которая предоставляет ответы. Эту роль можно использовать при вызове startChat() с существующей history .

import { GoogleGenerativeAI } from "@google/generative-ai";

// Access your API key (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(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);

Реализация расширенных вариантов использования

Распространенные случаи использования, описанные в предыдущем разделе этого руководства, помогут вам освоиться с API Gemini. В этом разделе описаны некоторые варианты использования, которые можно считать более продвинутыми.

Вызов функции

Вызов функций упрощает получение структурированных выходных данных из генеративных моделей. Затем вы можете использовать эти выходные данные для вызова других 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 });

Возможности управления созданием контента

Вы можете управлять созданием контента, настраивая параметры модели и используя настройки безопасности.

Настройте параметры модели

Каждое приглашение, которое вы отправляете в модель, включает значения параметров, которые управляют тем, как модель генерирует ответ. Модель может генерировать разные результаты для разных значений параметров. Узнайте больше о параметрах модели . Конфигурация сохраняется на протяжении всего срока существования экземпляра модели.

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 .