The Google AI Dart SDK is in public preview, which means its behavior and features could change in backward-incompatible ways. Preview releases should not be used in production.

Trang này được dịch bởi Cloud Translation API.

Làm quen với API Gemini trong ứng dụng Dart hoặc Flutter

Hướng dẫn này minh hoạ cách truy cập API Gemini cho ứng dụng Dart hoặc Flutter của bạn bằng cách sử dụng SDK Dart AI của Google. Bạn có thể sử dụng SDK này nếu không muốn làm việc trực tiếp với các API REST để truy cập vào các mô hình Gemini trong ứng dụng của mình.

Trong hướng dẫn này, bạn sẽ tìm hiểu cách thực hiện những việc sau:

Thiết lập dự án, bao gồm cả khoá API
Tạo văn bản bằng thông tin chỉ nhập bằng văn bản
Tạo văn bản từ dữ liệu nhập bằng văn bản và hình ảnh (đa phương thức)
Xây dựng cuộc trò chuyện nhiều lượt (trò chuyện)
Sử dụng tính năng phát trực tuyến để tương tác nhanh hơn

Ngoài ra, bài hướng dẫn này còn có các phần về các trường hợp sử dụng nâng cao (chẳng hạn như video nhúng và mã thông báo đếm) cũng như các tuỳ chọn để kiểm soát việc tạo nội dung.

Điều kiện tiên quyết

Hướng dẫn này giả định rằng bạn đã quen với việc tạo ứng dụng bằng Dart.

Để hoàn tất phần hướng dẫn này, hãy đảm bảo môi trường phát triển của bạn đáp ứng các yêu cầu sau:

Dart 3.2.0 trở lên

Thiết lập dự án

Trước khi gọi API Gemini, bạn cần thiết lập dự án, bao gồm cả việc thiết lập khoá API, thêm SDK vào các phần phụ thuộc của nhà xuất bản và khởi động mô hình.

Thiết lập khoá API

Để sử dụng API Gemini, bạn cần có một khoá API. Nếu bạn chưa có khoá, hãy tạo khoá trong Google AI Studio.

Lấy khoá API

Bảo mật khoá API

Bảo mật khoá API. Bạn không nên đưa trực tiếp khoá API vào mã hoặc kiểm tra các tệp chứa khoá vào các hệ thống quản lý phiên bản. Thay vào đó, bạn nên sử dụng kho lưu trữ bí mật cho khoá API của mình.

Tất cả các đoạn mã trong hướng dẫn này đều giả định rằng bạn đang truy cập khoá API dưới dạng một biến môi trường của quy trình. Nếu đang phát triển một ứng dụng Flutter, bạn có thể sử dụng String.fromEnvironment và truyền --dart-define=API_KEY=$API_KEY đến flutter build hoặc flutter run để biên dịch bằng khoá API, vì môi trường quy trình sẽ khác nhau khi chạy ứng dụng.

Cài đặt gói SDK

Để sử dụng API Gemini trong ứng dụng của riêng bạn, bạn cần add gói google_generative_ai vào ứng dụng Dart hoặc Flutter của mình:

Dart

dart pub add google_generative_ai

Flutter

flutter pub add google_generative_ai

Khởi động mô hình tạo sinh

Để có thể thực hiện bất kỳ lệnh gọi API nào, bạn cần nhập và khởi chạy mô hình tạo sinh.

import 'package:google_generative_ai/google_generative_ai.dart';

// Access your API key as an environment variable (see "Set up your API key" above)
final apiKey = Platform.environment['API_KEY'];
if (apiKey == null) {
  print('No \$API_KEY environment variable');
  exit(1);
}

final model = GenerativeModel(model: 'MODEL_NAME', apiKey: apiKey);

Khi chỉ định một mô hình, hãy lưu ý những điều sau:

Sử dụng mô hình dành riêng cho trường hợp sử dụng của bạn (ví dụ: gemini-pro-vision dành cho phương thức nhập đa phương thức). Trong hướng dẫn này, hướng dẫn cho mỗi cách triển khai liệt kê mô hình được đề xuất cho từng trường hợp sử dụng.

Lưu ý: Để biết thông tin chi tiết về các mô hình hiện có, bao gồm cả tính năng và giới hạn số lượng yêu cầu, hãy xem bài viết Mô hình Gemini. Giới hạn số lượng yêu cầu cho các mô hình Gemini Pro là 60 yêu cầu mỗi phút (RPM) và chúng tôi cung cấp các lựa chọn để yêu cầu tăng giới hạn tốc độ.

Triển khai các trường hợp sử dụng phổ biến

Bây giờ, dự án của bạn đã được thiết lập, bạn có thể khám phá cách sử dụng API Gemini để triển khai các trường hợp sử dụng khác nhau:

Tạo văn bản bằng thông tin chỉ nhập bằng văn bản
Tạo văn bản từ dữ liệu nhập bằng văn bản và hình ảnh (đa phương thức)
Xây dựng cuộc trò chuyện nhiều lượt (trò chuyện)
Sử dụng tính năng phát trực tuyến để tương tác nhanh hơn

Trong phần trường hợp sử dụng nâng cao, bạn có thể tìm thấy thông tin về API Gemini và nội dung nhúng.

Tạo văn bản từ phương thức nhập chỉ bằng văn bản

Khi câu lệnh đầu vào chỉ bao gồm văn bản, hãy sử dụng mô hình gemini-pro với phương thức generateContent để tạo đầu ra văn bản:

import 'dart:io';

import 'package:google_generative_ai/google_generative_ai.dart';

void main() async {
  // Access your API key as an environment variable (see "Set up your API key" above)
  final apiKey = Platform.environment['API_KEY'];
  if (apiKey == null) {
    print('No \$API_KEY environment variable');
    exit(1);
  }
  // For text-only input, use the gemini-pro model
  final model = GenerativeModel(model: 'gemini-pro', apiKey: apiKey);
  final content = [Content.text('Write a story about a magic backpack.')];
  final response = await model.generateContent(content);
  print(response.text);
}

Tạo văn bản bằng phương thức nhập văn bản và hình ảnh (đa phương thức)

Gemini cung cấp một mô hình đa phương thức (gemini-pro-vision) để bạn có thể nhập cả văn bản và hình ảnh. Hãy nhớ tham khảo các yêu cầu về hình ảnh để nhập.

Khi đầu vào của lời nhắc bao gồm cả văn bản và hình ảnh, hãy sử dụng mô hình gemini-pro-vision với phương thức generateContent để tạo đầu ra văn bản:

import 'dart:io';

import 'package:google_generative_ai/google_generative_ai.dart';

void main() async {
  // Access your API key as an environment variable (see "Set up your API key" above)
  final apiKey = Platform.environment['API_KEY'];
  if (apiKey == null) {
    print('No \$API_KEY environment variable');
    exit(1);
  }
  // For text-and-image input (multimodal), use the gemini-pro-vision model
  final model = GenerativeModel(model: 'gemini-pro-vision', apiKey: apiKey);
  final (firstImage, secondImage) = await (
    File('image0.jpg').readAsBytes(),
    File('image1.jpg').readAsBytes()
  ).wait;
  final prompt = TextPart("What's different between these pictures?");
  final imageParts = [
    DataPart('image/jpeg', firstImage),
    DataPart('image/jpeg', secondImage),
  ];
  final response = await model.generateContent([
    Content.multi([prompt, ...imageParts])
  ]);
  print(response.text);
}

Xây dựng cuộc trò chuyện nhiều lượt (trò chuyện)

Khi dùng Gemini, bạn có thể tạo các cuộc trò chuyện dạng tự do qua nhiều lượt. SDK đơn giản hoá quy trình bằng cách quản lý trạng thái của cuộc trò chuyện, vì vậy, không giống như generateContent, bạn không phải tự lưu trữ nhật ký cuộc trò chuyện.

Để tạo một cuộc trò chuyện nhiều lượt (như cuộc trò chuyện), hãy sử dụng mô hình gemini-pro và khởi động cuộc trò chuyện bằng cách gọi startChat(). Sau đó, sử dụng sendMessage() để gửi tin nhắn mới cho người dùng. Thao tác này cũng sẽ thêm tin nhắn và câu trả lời vào nhật ký trò chuyện.

Có 2 tuỳ chọn cho role liên kết với nội dung trong cuộc trò chuyện:

user: vai trò đưa ra lời nhắc. Giá trị này là giá trị mặc định cho lệnh gọi sendMessage và hàm sẽ gửi một ngoại lệ nếu được truyền một vai trò khác.
model: vai trò đưa ra câu trả lời. Bạn có thể dùng vai trò này khi gọi startChat() bằng history hiện có.

import 'dart:io';

import 'package:google_generative_ai/google_generative_ai.dart';

Future<void> main() async {
  // Access your API key as an environment variable (see "Set up your API key" above)
  final apiKey = Platform.environment['API_KEY'];
  if (apiKey == null) {
    print('No \$API_KEY environment variable');
    exit(1);
  }
  // For text-only input, use the gemini-pro model
  final model = GenerativeModel(
      model: 'gemini-pro',
      apiKey: apiKey,
      generationConfig: GenerationConfig(maxOutputTokens: 100));
  // Initialize the chat
  final chat = model.startChat(history: [
    Content.text('Hello, I have 2 dogs in my house.'),
    Content.model([TextPart('Great to meet you. What would you like to know?')])
  ]);
  var content = Content.text('How many paws are in my house?');
  var response = await chat.sendMessage(content);
  print(response.text);
}

Sử dụng tính năng phát trực tuyến để tương tác nhanh hơn

Theo mặc định, mô hình sẽ trả về một phản hồi sau khi hoàn tất toàn bộ quá trình tạo. Bạn có thể đạt được tương tác nhanh hơn bằng cách không đợi toàn bộ kết quả, mà thay vào đó sử dụng phương thức truyền trực tuyến để xử lý một phần kết quả.

Ví dụ sau cho thấy cách triển khai truyền trực tuyến bằng phương thức generateContentStream để tạo văn bản từ lời nhắc nhập văn bản và hình ảnh.

// ...

final response = model.generateContentStream([
  Content.multi([prompt, ...imageParts])
]);
await for (final chunk in response) {
  print(chunk.text);
}

// ...

Bạn có thể áp dụng phương pháp tương tự cho các trường hợp sử dụng chỉ nhập văn bản và trò chuyện.

// Use streaming with text-only input
final response = model.generateContentStream(content);

// Use streaming with multi-turn conversations (like chat)
final response = chat.sendMessageStream(content);

Triển khai các trường hợp sử dụng nâng cao

Các trường hợp sử dụng phổ biến được mô tả trong phần trước của hướng dẫn này giúp bạn làm quen với việc sử dụng API Gemini. Phần này mô tả một số trường hợp sử dụng có thể được coi là nâng cao hơn.

Gọi hàm

Tính năng gọi hàm giúp bạn dễ dàng nhận được kết quả dữ liệu có cấu trúc từ các mô hình tạo sinh. Sau đó, bạn có thể sử dụng các kết quả đầu ra này để gọi các API khác và trả về dữ liệu phản hồi liên quan cho mô hình. Nói cách khác, tính năng gọi hàm giúp bạn kết nối các mô hình tạo sinh với hệ thống bên ngoài để nội dung được tạo bao gồm thông tin chính xác và mới nhất. Hãy tìm hiểu thêm trong hướng dẫn gọi hàm.

Sử dụng tính năng nhúng

Nhúng là kỹ thuật dùng để biểu thị thông tin dưới dạng danh sách các số dấu phẩy động trong một mảng. Với Gemini, bạn có thể biểu thị văn bản (từ, câu và khối văn bản) dưới dạng vectơ hoá, giúp bạn dễ dàng so sánh và đối chiếu các tệp nhúng. Ví dụ: hai văn bản có cùng một chủ đề hoặc tình cảm nên có các nội dung nhúng tương tự nhau, có thể được xác định thông qua các kỹ thuật so sánh toán học, chẳng hạn như tính tương đồng về giá trị cos.

Sử dụng mô hình embedding-001 với phương thức embedContent (hoặc phương thức batchEmbedContent) để tạo các bản nhúng. Ví dụ sau đây tạo một phép nhúng cho một chuỗi:

final model = GenerativeModel(model: 'embedding-001', apiKey: apiKey);
final content = Content.text('The quick brown fox jumps over the lazy dog.');
final result = await model.embedContent(content);
print(result.embedding.values);

Số lượng mã thông báo

Khi sử dụng lời nhắc dài, bạn nên đếm mã thông báo trước khi gửi bất kỳ nội dung nào đến mô hình. Các ví dụ sau đây minh hoạ cách sử dụng countTokens() cho nhiều trường hợp sử dụng:

// For text-only input
final tokenCount = await model.countTokens(Content.text(prompt));
print('Token count: ${tokenCount.totalTokens}');

// For text-and-image input (multimodal)
final tokenCount = await model.countTokens([
  Content.multi([prompt, ...imageParts])
]);
print('Token count: ${tokenCount.totalTokens}');

// For multi-turn conversations (like chat)
final prompt = Content.text(message);
final allContent = [...chat.history, prompt];
final tokenCount = await model.countTokens(allContent);
print('Token count: ${tokenCount.totalTokens}');

Các tuỳ chọn kiểm soát việc tạo nội dung

Bạn có thể kiểm soát việc tạo nội dung bằng cách định cấu hình các tham số mô hình và sử dụng các chế độ cài đặt an toàn.

Lưu ý rằng việc truyền generationConfig hoặc safetySettings sang phương thức yêu cầu mô hình (như generateContent) sẽ ghi đè toàn bộ đối tượng cấu hình có cùng tên được truyền trong getGenerativeModel.

Định cấu hình thông số mô hình

Mọi lời nhắc bạn gửi đến mô hình đều bao gồm các giá trị tham số kiểm soát cách mô hình tạo ra một phản hồi. Mô hình này có thể tạo ra các kết quả khác nhau cho các giá trị tham số khác nhau. Tìm hiểu thêm về Tham số mô hình. Cấu hình được duy trì trong suốt thời gian thực thể mô hình của bạn tồn tại.

final generationConfig = GenerationConfig(
  stopSequences: ["red"],
  maxOutputTokens: 200,
  temperature: 0.9,
  topP: 0.1,
  topK: 16,
);
final model = GenerativeModel(
  model: 'MODEL_NAME',
  apiKey: apiKey,
  generationConfig: generationConfig,
);

Sử dụng các chế độ cài đặt an toàn

Bạn có thể sử dụng các chế độ cài đặt an toàn để điều chỉnh khả năng nhận được những câu trả lời có thể bị coi là gây hại. Theo mặc định, các chế độ cài đặt an toàn sẽ chặn nội dung có xác suất là nội dung không an toàn trên mọi phương diện ở mức trung bình và/hoặc cao. Tìm hiểu thêm về Chế độ cài đặt an toàn.

Sau đây là cách đặt một chế độ cài đặt an toàn:

final safetySettings = [
  SafetySetting(HarmCategory.harassment, HarmBlockThreshold.high)
];
final model = GenerativeModel(
  model: 'MODEL_NAME',
  apiKey: apiKey,
  safetySettings: safetySettings,
);

Bạn cũng có thể đặt nhiều chế độ cài đặt an toàn:

final safetySettings = [
  SafetySetting(HarmCategory.harassment, HarmBlockThreshold.high),
  SafetySetting(HarmCategory.hateSpeech, HarmBlockThreshold.high),
];

Bước tiếp theo

Thiết kế lời nhắc là quá trình tạo các câu lệnh để khơi gợi phản hồi mong muốn từ các mô hình ngôn ngữ. Việc viết câu lệnh có cấu trúc hợp lý là một phần cần thiết để đảm bảo câu trả lời chính xác và chất lượng cao từ mô hình ngôn ngữ. Tìm hiểu các phương pháp hay nhất để viết gợi ý.
Gemini cung cấp một số biến thể mô hình để đáp ứng nhu cầu của nhiều trường hợp sử dụng, chẳng hạn như loại dữ liệu đầu vào và độ phức tạp, cách triển khai cho cuộc trò chuyện hoặc các tác vụ khác về ngôn ngữ hộp thoại cũng như các quy tắc ràng buộc về kích thước. Tìm hiểu về các mô hình Gemini hiện có.
Gemini đưa ra các tuỳ chọn để yêu cầu tăng giới hạn tốc độ. Giới hạn tốc độ cho các mô hình Genmini Pro là 60 yêu cầu mỗi phút (RPM).