AGTCloud API Docs
Hướng dẫnAPI ReferenceTích hợp và tài nguyênCập nhật và hỗ trợ
Web Search

Gemini Search Grounding

Sử dụng Google Search Grounding để liên kết các đoạn trả lời với nguồn trang web.

Gemini Search Grounding cho phép mô hình Gemini hỗ trợ khả năng này sử dụng Google Search để lấy thông tin gần đây và liên kết các đoạn trả lời với nguồn web qua groundingMetadata.

Grounding không chỉ là “bật tìm kiếm”. Ứng dụng còn cần đọc ánh xạ giữa truy vấn, nguồn và đoạn văn bản để hiển thị trích dẫn có thể kiểm tra trên giao diện.

Giao thức hỗ trợ không có nghĩa mô hình hỗ trợ

Generate Content có thể biểu diễn công cụ Google Search, nhưng phạm vi khả dụng phụ thuộc vào mô hình và tài khoản hiện tại. Kiểm tra mô hình trong Danh mục mô hình trước, rồi tham khảo Gemini Generate Content Reference.

Gửi yêu cầu Grounding

Đường dẫn Gemini gốc được tạo bằng cách nối /v1beta vào Origin của trang; không nối /v1beta vào Base URL đã chứa /v1:

curl --request POST \
  'https://api.agtcloud.cn/v1beta/models/MODEL_ID:generateContent' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Hôm nay có những tin trí tuệ nhân tạo nào đáng chú ý? Hãy cung cấp nguồn."
          }
        ]
      }
    ],
    "tools": [
      {
        "google_search": {}
      }
    ]
  }'

Mô hình quyết định có cần tìm kiếm hay không và có thể tạo một hoặc nhiều truy vấn. Không giả định mỗi lần bật công cụ đều tạo Grounding Metadata.

Quy trình xử lý Grounding

1. Gửi câu hỏi và công cụ tìm kiếm

Đặt câu hỏi của người dùng trong contents[].parts và bật Google Search trong tools.

2. Đọc văn bản trả lời

Đọc văn bản do mô hình tạo từ content.parts của ứng viên; không giả định luôn chỉ có một ứng viên hoặc một Part.

3. Đọc Grounding Metadata

Lưu truy vấn tìm kiếm, nguồn web và liên kết giữa các đoạn trả lời với chỉ số nguồn.

4. Hiển thị trích dẫn có thể nhấp

Chèn ký hiệu trích dẫn theo vị trí kết thúc đoạn hoặc hiển thị thẻ nguồn cạnh câu trả lời để người dùng quay lại trang gốc kiểm tra.

Hiểu groundingMetadata

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {"text": "Theo các báo cáo gần đây, những tiến triển liên quan gồm…"}
        ]
      },
      "groundingMetadata": {
        "webSearchQueries": [
          "trí tuệ nhân tạo tin tức hôm nay"
        ],
        "groundingChunks": [
          {
            "web": {
              "uri": "https://example.com/article",
              "title": "Tiêu đề nguồn"
            }
          }
        ],
        "groundingSupports": [
          {
            "segment": {
              "startIndex": 0,
              "endIndex": 12,
              "text": "Theo các báo cáo gần đây"
            },
            "groundingChunkIndices": [0]
          }
        ]
      }
    }
  ]
}
TrườngMục đích sử dụng phía ứng dụng
webSearchQueriesGhi truy vấn tìm kiếm mà mô hình thực sự sử dụng để hỗ trợ khắc phục sự cố và giải thích phạm vi tìm kiếm
groundingChunksLưu thông tin nguồn như URI và tiêu đề trang web
groundingSupportsÁnh xạ đoạn văn bản trả lời đến một hoặc nhiều chỉ số nguồn

Phản hồi có thể thiếu một số trường này; ứng dụng cần dùng truy cập tùy chọn và mảng rỗng làm giá trị mặc định.

Chèn trích dẫn vào văn bản

Khi chèn trích dẫn, xử lý theo segment.endIndex từ lớn đến nhỏ để lần chèn trước không làm thay đổi vị trí tiếp theo:

function addCitations(text, supports = [], chunks = []) {
  const sorted = [...supports].sort(
    (a, b) => (b.segment?.endIndex ?? 0) - (a.segment?.endIndex ?? 0),
  );

  for (const support of sorted) {
    const endIndex = support.segment?.endIndex;
    if (endIndex == null) continue;

    const links = (support.groundingChunkIndices ?? [])
      .map((index) => {
        const source = chunks[index]?.web;
        return source?.uri ? `[${index + 1}](${source.uri})` : null;
      })
      .filter(Boolean);

    if (links.length > 0) {
      text = `${text.slice(0, endIndex)}${links.join('')}${text.slice(endIndex)}`;
    }
  }

  return text;
}

Khi hiển thị nội dung mô hình trả về trong trình duyệt, hãy xử lý Markdown hoặc HTML an toàn và thêm thuộc tính bảo mật cho liên kết ngoài mở trong tab mới.

Thất bại và phương án dự phòng

Hiện tượngCách xử lý
Không có groundingMetadataHiển thị câu trả lời bình thường và nêu rõ lần này không có nguồn Grounding để hiển thị
Chỉ số nguồn vượt phạm viBỏ qua liên kết không hợp lệ và ghi phản hồi đã che thông tin nhạy cảm; không chèn liên kết sai
Vị trí văn bản không khớpChuyển sang danh sách nguồn cuối câu trả lời; không chèn trích dẫn ở vị trí sai
Tìm kiếm thất bạiDựa trên lỗi phản hồi để thử lại có giới hạn hoặc chuyển sang trả lời không tìm kiếm
Nội dung nguồn mâu thuẫnHiển thị nguồn từ nhiều bên và ngày để người dùng đánh giá; không che giấu khác biệt quan trọng

Kiểm tra trước khi đưa vào production

  • Mô hình hiện tại hỗ trợ Google Search Grounding.
  • Gemini Endpoint dùng Origin của trang, không tạo /v1/v1beta.
  • Văn bản trả lời, truy vấn, nguồn và ánh xạ đoạn được lưu riêng.
  • Chỉ số trích dẫn không hợp lệ không làm trang bị lỗi.
  • Nội dung web ngoài không được coi trực tiếp là chỉ dẫn nghiệp vụ đáng tin cậy.
  • Không tạo Citation giả khi không có nguồn.

Nếu ứng dụng dùng Chat thay vì cấu trúc Gemini gốc, hãy dùng các trường tìm kiếm Chat mà mô hình mục tiêu được xác nhận hỗ trợ; không sao chép trực tiếp bộ phân tích groundingMetadata.

Trên trang này