Sử dụng API tổng hợp địa điểm để tạo điểm xếp hạng vị trí tuỳ chỉnh

Mục tiêu

Việc tìm được địa điểm lý tưởng, cho dù đó là một khách sạn cho kỳ nghỉ sắp tới hay một căn hộ phù hợp với gia đình, thường là một quá trình tốn thời gian và gây khó chịu khi phải so sánh nhiều lựa chọn. Điều gì sẽ xảy ra nếu bạn có thể giúp người dùng dễ dàng hơn bằng cách cung cấp một chỉ số tuỳ chỉnh cho biết mức độ phù hợp của một khách sạn đối với khách du lịch hoặc xếp hạng các căn hộ dựa trên mức độ phù hợp với gia đình, biến một việc nhà tẻ nhạt thành một quyết định dễ dàng.

Tài liệu này trình bày cách sử dụng Places Aggregate API để tạo điểm số vị trí tuỳ chỉnh, linh hoạt, dựa trên mật độ của các địa điểm trong một khu vực địa lý xác định. Điểm số (thứ hạng bằng số dựa trên tiêu chí mà bạn chỉ định) sẽ cho biết ngay mức độ phù hợp của vị trí đó với nhu cầu của họ.

Hãy xem xét một trường hợp mà bạn đang quảng bá khách sạn ở một thành phố và muốn làm nổi bật những khách sạn ở các khu vực du lịch hấp dẫn nhất bằng cách tạo điểm số phù hợp với khách du lịch. Sử dụng Places Aggregate API để đếm số lượng loại địa điểm có liên quan ở gần mỗi khách sạn. Ví dụ: bạn biết rằng khách hàng của mình coi trọng những khách sạn ở gần một số địa điểm sau:

• Nhà hàng và quán cà phê
• Công viên và bảo tàng
• Cửa hàng quần áo

Bằng cách áp dụng trọng số quan trọng cho số lượng của các loại địa điểm đã chọn này, bạn có thể tính toán điểm tổng thể cho từng vị trí khách sạn. Điểm số này phản ánh mức độ phù hợp tổng thể của vị trí, dựa trên các địa điểm lân cận. Trọng số được chỉ định cho từng loại địa điểm phải phù hợp với trường hợp sử dụng cụ thể của bạn và những gì quan trọng đối với đối tượng mục tiêu. Tài liệu này sẽ sử dụng điểm số phù hợp với khách du lịch làm ví dụ chính, nhưng bạn có thể tạo điểm số để phản ánh nhu cầu và đặc điểm nhân khẩu học của người dùng.

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

Trước khi đọc tài liệu này, bạn nên làm quen với tài liệu sau:

• Tài liệu dành cho nhà phát triển Places Aggregate API để tìm hiểu thông tin kỹ thuật chi tiết và các thông số có sẵn.
• [Không bắt buộc] Tài liệu dành cho nhà phát triển về Gemini Developer API để tìm hiểu cách gọi Gemini bằng API và được dùng trong tài liệu này như một lựa chọn để tạo điểm số tuỳ chỉnh về vị trí.

Bản minh hoạ

Bản minh hoạ này cho thấy ví dụ về điểm số tuỳ chỉnh về vị trí đang hoạt động. Chọn một thành phố trong trình đơn thả xuống rồi nhấp vào nút Tính điểm tuỳ chỉnh để hiển thị điểm tuỳ chỉnh cho vị trí của 5 vị trí được điền sẵn.

Chọn các loại địa điểm có liên quan

Bước đầu tiên để xây dựng điểm số tuỳ chỉnh về vị trí là quyết định loại địa điểm phù hợp với khách hàng của bạn trong Bảng A. Vì chúng tôi đang tạo điểm số phù hợp với khách du lịch, nên chúng tôi đã chọn các loại địa điểm sau đây mà khách du lịch sẽ muốn ở gần trong thời gian lưu trú:

• nhà hàng
• công viên
• clothing_store
• viện bảo tàng
• coffee_shop

Tiếp theo, hãy chỉ định trọng số cho từng loại địa điểm này, phản ánh tầm quan trọng tương đối của loại địa điểm đó trong điểm số cuối cùng. Bạn nên xác định trọng số dựa trên những yếu tố quan trọng nhất đối với trường hợp sử dụng và lựa chọn ưu tiên của người dùng. Đối với ví dụ này, thang đo trọng số sẽ nằm trong khoảng từ 0 đến 1, như sau:

Gọi Places Aggregate API

Giờ đây, khi đã có danh sách các loại địa điểm mà bạn quan tâm, bước tiếp theo là gọi Places Aggregate API.

Places Aggregate API yêu cầu bộ lọc vị trí. Đối với ví dụ này, hãy sử dụng circle, với tâm latLng là vị trí của khách sạn và radius là 500 m. Bạn cũng có thể đặt ratingFilter để trả về những địa điểm có điểm xếp hạng từ 3,8 đến 5, loại trừ những địa điểm có điểm xếp hạng thấp hơn khỏi số lượng.

Thử nghiệm bằng cách thay đổi chế độ cài đặt của bộ lọc vị trí cho trường hợp sử dụng cụ thể của bạn. Ví dụ: bạn có thể muốn ghi lại những địa điểm trong bán kính rộng hơn so với vĩ độ và kinh độ trung tâm bằng cách tăng giá trị bán kính. Ngoài ra, bạn có thể muốn sử dụng một phương thức khác để đặt khu vực tìm kiếm, chẳng hạn như Khu vực hoặc Khu vực tuỳ chỉnh.

Làm quen với phần bộ lọc vị trí trong tài liệu Places Aggregate API để tìm hiểu về các lựa chọn mà bạn có thể sử dụng.

Gọi Places Aggregate API cho từng loại địa điểm và vị trí mà bạn muốn tạo điểm số tuỳ chỉnh. Ví dụ: gọi Loại địa điểm của nhà hàng cho một trong các khách sạn của bạn:

curl --location 'https://areainsights.googleapis.com/v1:computeInsights' \
--header 'X-Goog-Api-Key: API_KEY \
--header 'Content-Type: application/json' \
--data '{
    "insights": [
        "INSIGHT_COUNT"
    ],
    "filter": {
        "locationFilter": {
            "circle": {
                "latLng": {
                    "latitude": 51.51611,
                    "longitude": -0.12726
                },
                "radius": 500
            }
        },
        "typeFilter": {
            "includedTypes": [
                "restaurant"
            ]
        },
        "ratingFilter": {
            "minRating": 3.8,
            "maxRating": 5
        }
    }
}'

Sau khi hoàn tất tất cả các lệnh gọi đến API, bạn sẽ có dữ liệu như sau cho từng vị trí:

Tạo điểm số tuỳ chỉnh về vị trí

Giờ đây, bạn đã có số lượng địa điểm và trọng số cho từng loại địa điểm của từng vị trí. Giờ đây, bạn có thể tạo điểm số tuỳ chỉnh về vị trí. Trong phần này, chúng ta sẽ thảo luận về 2 lựa chọn: sử dụng một thuật toán cục bộ hoặc sử dụng Gemini Developer API.

Cách 1: Sử dụng một thuật toán

Lựa chọn đầu tiên mà chúng ta sẽ đề cập là sử dụng một thuật toán cục bộ để tạo điểm số bằng cách sử dụng trọng số và số lượng cho từng Loại địa điểm. Chuẩn hoá điểm số này theo thang điểm từ 0 đến 5, trong đó giá trị càng cao thì khu vực càng hấp dẫn dựa trên tiêu chí của bạn. Đối với ví dụ này, hãy tạo 2 đối tượng JavaScript từ dữ liệu ở trên:

    {
      "restaurant": 56,
      "park": 3,
      "clothing_store": 32,
      "museum": 8,
      "coffee_shop": 41
    }
    

    {
      "restaurant": 0.8,
      "park": 0.6,
      "clothing_store": 0.3,
      "museum": 0.2,
      "coffee_shop": 0.5
    }
    

Tạo điểm từ số lượng và trọng số bằng cách nhân itemCounts với typeWeights, rồi cộng các kết quả vào weightedCount tổng thể:

let weightedCount = 0;
for (const itemType in itemCounts) {
  weightedCount += itemCounts[itemType] * typeWeights[itemType];
}
weightedCount = weightedCount.toFixed(2);

Trong ví dụ này, kết quả của bước này là: 78,3.

Giờ đây, bạn có thể sử dụng phương pháp chuẩn hoá theo hàm lôgarit để tạo điểm số cuối cùng cho vị trí này theo thang điểm từ 0 đến 5:

if (weightedCount === 0) {
   normalizedScore = 0;
} else {
   normalizedScore = Math.log(weightedCount + 1);
}

// Clamp between 0 and 5
normalizedScore = Math.max(0, Math.min(5, normalizedScore));

Trong ví dụ này, điểm số cuối cùng là: 4,36 (làm tròn đến 2 chữ số thập phân).

Cách 2: Sử dụng Gemini Developer API

Ngoài việc sử dụng thuật toán cục bộ, Gemini Developer API còn cung cấp một cách hiệu quả để tính điểm vị trí tuỳ chỉnh cho tất cả các vị trí. Bạn chỉ cần cung cấp dữ liệu về số lượng và trọng số cùng với hướng dẫn của hệ thống cho tất cả các vị trí khách sạn của mình.

Phương thức này đặc biệt hữu ích nếu bạn có thông tin chi tiết mà bạn muốn đưa vào tính toán, chẳng hạn như:

• Nội dung mô tả bằng văn bản cho từng vị trí khách sạn, ví dụ: "Vị trí này phù hợp với gia đình và khu vực này yên tĩnh vào ban đêm".
• Thông tin về người dùng của bạn, chẳng hạn như: "Người dùng này đang đặt phòng cho gia đình và thích một khu vực yên tĩnh ở vị trí trung tâm".

Gemini Developer API có thể hiểu và tính đến dữ liệu định tính này, dẫn đến điểm số tinh vi và phù hợp hơn ngoài phương pháp thuần tuý về toán học.

Bằng cách sử dụng Gemini Developer API, ngoài bảng trọng số và loại địa điểm ở trên, bạn có thể có dữ liệu mô tả cho từng vị trí như sau:

Bạn có thể đưa những nội dung mô tả định tính này cùng với mọi thông tin hoặc lựa chọn ưu tiên của người dùng vào câu lệnh cho Gemini.

Hướng dẫn về hệ thống

Gemini cần có hướng dẫn cùng với dữ liệu thô để biết rằng hệ thống dự kiến sẽ tạo điểm số cho từng vị trí dựa trên các điểm dữ liệu được cung cấp. Sau đây là ví dụ về chỉ dẫn hệ thống để đạt được điều này:

You will be given a json file containing details about a number of locations grouped by their latitude and longitudes.

Within the location details is information about the count of places nearby the location that match a specific category, and the weighting of importance of that category, between 0 - 1.

You will also be given information about the user's preference, and a description of each location. Take this into consideration when generating scores.

Generate a location suitability score taking these into account for each location. The score should be between 1 - 5 inclusive, to two decimal places. The minimum score a location can receive is 1.

Output in JSON

Các chỉ dẫn hệ thống ở trên cho Gemini biết dữ liệu cần dự kiến và dữ liệu đầu ra dự kiến của mô hình AI. Chỉ dẫn này cũng yêu cầu đầu ra ở định dạng JSON.

Đầu ra có cấu trúc

Mặc dù đã yêu cầu Gemini xuất kết quả ở định dạng JSON, nhưng chúng ta cần cụ thể hơn về cấu trúc của kết quả đầu ra để biết những gì cần mong đợi khi truy vấn bằng mã. Để làm việc này, chúng ta có thể thêm một chỉ dẫn đầu ra có cấu trúc khác vào yêu cầu, bằng cách sử dụng trường responseSchema trong Gemini API. Thao tác này sử dụng một đối tượng giản đồ OpenAPI để hạn chế đầu ra của mô hình.

Ví dụ:

{
  "type": "array",
  "description": "Array of location data with score",
  "items": {
    "type": "object",
    "properties": {
      "location": {
        "type": "object",
        "description": "Geographical coordinates of the location",
        "properties": {
          "latitude": {
            "type": "number",
            "format": "float",
            "description": "Latitude of the location"
          },
          "longitude": {
            "type": "number",
            "format": "float",
            "description": "Longitude of the location"
          }
        },
        "required": [
          "latitude",
          "longitude"
        ]
      },
      "score": {
        "type": "string",
        "description": "A score associated with the location"
      }
    },
    "required": [
      "location",
      "score"
    ]
  }
}

Ví dụ này yêu cầu Gemini xuất một mảng JavaScript có nội dung như sau:

• Vĩ độ và kinh độ của vị trí
• Điểm số tuỳ chỉnh về vị trí

Khi sử dụng chỉ dẫn hệ thống và đầu ra có cấu trúc ở trên, câu trả lời của Gemini cho một vị trí sẽ trông như sau, trong đó score là điểm số tuỳ chỉnh của vị trí:

[
  {
    "location": {
      "latitude": 51.51611,
      "longitude": -0.12726
    },
    "score": "4.13"
  }
]

Hiển thị điểm số

Sau khi bạn tạo điểm số tuỳ chỉnh về vị trí cho từng vị trí bằng một trong các phương thức được mô tả, điểm số đó có thể xuất hiện cùng với thông tin chi tiết về khách sạn của bạn hoặc được dùng làm lựa chọn lọc tìm kiếm. Ví dụ: "cho tôi xem những nơi có điểm phù hợp với khách du lịch cao". Điều này sẽ giúp khách hàng đưa ra quyết định dựa trên dữ liệu khi đặt chỗ.

Kết luận

Việc sử dụng điểm số vị trí tuỳ chỉnh có thể là một công cụ hữu ích giúp người dùng có cái nhìn tổng quan nhanh về mức độ phù hợp của một khu vực. Tài liệu này minh hoạ cách tạo điểm số tuỳ chỉnh về vị trí cho nhiều vị trí bằng cách sử dụng 5 loại địa điểm riêng biệt. Bạn có thể sửa đổi cách triển khai này cho phù hợp với nhu cầu của mình và kết hợp các loại địa điểm tương tự vào một yêu cầu để trả về tổng số lượng của các loại đó, nhằm cung cấp cho giải pháp tính điểm vị trí tuỳ chỉnh của bạn.

Hãy dùng Places Aggregate API ngay hôm nay để tạo điểm số vị trí hữu ích, giúp khách hàng đưa ra quyết định sáng suốt dựa trên vị trí!

Người đóng góp

Henrik Valve | Kỹ sư DevX