开发者文档
产品描述
Population Dynamics Insights (PDI) 是一种嵌入数据集，可将有关人类行为以及我们与环境互动的数据提炼为简洁、可用于分析的嵌入内容（或“数字指纹”），并提供特定位置的数据。
这些嵌入可捕获汇总数据中的模式，例如搜索趋势、繁忙程度趋势和环境条件（地图、空气质量、天气），从而提供丰富且特定于位置的人群与周围环境互动情况的快照。这些嵌入内容在空间和时间上进行了汇总，可确保隐私保护，同时支持细致的空间分析和预测，适用于从公共卫生到社会经济建模等各种应用。
产品概览
人口动态嵌入是使用专门构建的机器学习模型生成的，该模型经过了丰富特征集的训练，并转换为精简的向量表示形式。这些嵌入是根据以下内容训练和生成的：
- 汇总的搜索趋势：搜索数据反映的区域兴趣和关注点。
- 汇总的 Google 地图数据（包括繁忙程度）：区域内的设施、服务和商家，以及本地访问趋势。
- 汇总天气和空气质量：与气候相关的指标，包括温度和空气质量。
这些特征在邮政编码级别进行汇总，以生成可保护隐私的本地化、情境感知型嵌入。PDI 是一个持续的时间序列数据集，每月处理和划分新的数据切片。数据会在下一个日历月的最后一天之前刷新并附加到数据表中（例如，2 月的数据会在 3 月 31 日之前发布）。
前提条件
如需访问人口动态嵌入内容，您必须获得相应权限。如果您没有访问权限，请与您的销售代表或客户工程代表联系。
- 在 Cloud 控制台中启用 Analytics Hub API。
- 在 Cloud 控制台中启用 BigQuery API。
- 对 BigQuery 产品有实际操作经验。
- 确保您的账号具有 Analytics Hub Subscription Owner (
roles/analyticshub.subscriptionOwner) 角色，才能执行订阅者任务。 - 确保您的账号拥有 BigQuery User (
roles/bigquery.user) 角色，以便创建数据集。
推荐的训练
如果您是初次使用嵌入或 BigQuery Machine Learning，我们强烈建议您在开始分析之前完成以下培训材料：
- 机器学习速成课程：嵌入：这是一篇基础性文章，简要介绍了机器学习模型如何使用嵌入将高维数据转换为低维空间，同时保留语义关系。
- 向量搜索和嵌入使用入门：一项实用的 Google Cloud Skills Boost 实验，介绍了向量嵌入、语义相似性以及如何在更广泛的 Google Cloud 生态系统中利用嵌入。
- BigQuery Machine Learning (BQML) 教程：由于 PDI 数据集托管在 BigQuery 中，因此您可以使用标准 SQL 直接在嵌入上训练和执行机器学习模型，而无需导出数据。
使用嵌入
了解数据
在开始分析之前，请花点时间查看架构结构。
数据集组织
嵌入内容会整理到单独的 BigQuery 表中，每个国家/地区或测试区域对应一个表。
嵌入向量的结构
features 列是一个 330 维向量（在 BigQuery 中存储为 REPEATED FLOAT 数组）。数组的每个部分都对应于人口动态模型提取的特定数据信号。
了解这种结构有助于进行特征消融（例如，确定搜索行为与天气相比，对销售额的预测程度如何）。
| 向量索引 | 数据源 | 说明 |
|---|---|---|
| 0 - 127 | 汇总搜索趋势 | 反映区域性兴趣和关注点（例如，对“健身房”“流感症状”“奢侈品”的搜索）。 |
| 128 - 255 | 地图与繁忙程度 | 捕获建成环境（医院、公园、学校等 POI）和人类访问情况，以显示感兴趣的地点。 |
| 256 - 329 | 天气和空气质量 | 捕获环境背景信息（温度、降水、空气质量）。 |
关键列和元数据
嵌入表包含空间和时间元数据，可实现地理空间分析、过滤以及与其他服务的互操作性。
由于单个邮政编码有时可能会跨越行政边界（例如县界），因此行政区字段以数组形式提供。
geo_id：与相应邮政编码相关联的唯一地点 ID。geo_name：相应地区的邮政编码字符串（例如'90210'）。administrative_area_level_1_names：顶级边界的人类可读名称列表 (ARRAY<STRING>)，例如['California']。administrative_area_level_1_ids：相应邮政编码所处的顶级行政边界（例如州或省）的唯一地点 ID 的列表 (ARRAY<STRING>)。administrative_area_level_2_names：次要边界的人类可读名称列表 (ARRAY<STRING>)，例如['Los Angeles County']。administrative_area_level_2_ids：相应邮政编码所对应的次级行政边界（例如县或区）的唯一地点 ID 的列表 (ARRAY<STRING>)。features：核心的 330 维嵌入向量，以原生方式存储为ARRAY<FLOAT64>。使用 Python 将此数据加载到 Pandas 中需要将其扁平化或转换为 NumPy 矩阵。snapshot_date：格式为YYYY-MM-DD的DATE，已标准化为仅使用每月的第一天。表示用于汇总输入特征以生成嵌入数据的特定月度时间段。例如，2026 年 4 月的数据将采用2026-04-01格式。
准备标准答案数据
若要使用人口动态嵌入，您的标准答案数据必须汇总到受支持的地理边界（邮政编码）。
方法 1：将嵌入纳入现有模型
- 准备基于现有模型的标准答案：使用嵌入作为地理空间协变量来增强现有模型。
- 训练误差校正模型：通过将嵌入内容集成到以下模型中来改进现有模型：该模型会获取原始模型输出、预期值或标准答案以及嵌入内容，以学习新的误差校正模型。
方法 2：针对特定使用情形进行调优
- 选择预测模型类型：任何模型（例如 GBDT、MLP 或线性模型）均可用于预测。
- 使用嵌入进行预测：将人口动态嵌入与其他情境数据一起用作输入特征，以提高预测准确性。
快速入门代码段
您可以使用这些代码段来验证您的访问权限并了解数据格式。
1. SQL：提取特定月份的嵌入内容
由于 PDI 是时序数据集，因此您通常应按 snapshot_date 进行过滤，以免返回多个月份的重复邮政编码。日期必须始终设置为 -01。
SELECT
snapshot_date,
geo_name AS postal_code,
geo_id AS place_id,
features -- The 330-dim vector
FROM
`your-project.population_dynamics___us___domestic.v1_postal_code.embeddings_table`
WHERE
snapshot_date = '2025-10-01' -- You must use the first of the month ('-01')
LIMIT 10;
2. SQL：按行政区域过滤（取消嵌套数组）
由于邮政编码可以跨越多个行政边界，因此 administrative_area_* 字段以数组形式存储。如需过滤特定州（例如“加利福尼亚州”）内的所有邮政编码，您必须使用 BigQuery 的 UNNEST() 函数。
SELECT
snapshot_date,
geo_name AS postal_code,
admin1_name
FROM
your-project.population_dynamics___us___domestic.v1_postal_code.embeddings_table,
UNNEST(administrative_area_level_1_names) AS admin1_name
WHERE
-- On or after October 2025
snapshot_date >= '2025-10-01' -- You must use the first of the month ('-01')
AND admin1_name = 'California'
LIMIT 10;
3. SQL：查找相似的地点
此查询可识别行为相似的位置，而无需外部数据。它使用 ML.DISTANCE 函数计算余弦相似度，并返回目标邮政编码的最佳匹配项。
WITH TargetLocation AS (
SELECT features AS target_vector
FROM `your-project.population_dynamics___us___domestic.v1_postal_code.embeddings_table`
WHERE snapshot_date = '2025-10-01' -- You must use the first of the month ('-01')
AND geo_name = '90210' -- Replace with your target postal code
LIMIT 1
)
SELECT
t.geo_name AS postal_code,
-- Calculate Similarity (1.0 is identical, 0.0 is dissimilar)
(1 - ML.DISTANCE(t.features, p.target_vector, 'COSINE')) AS similarity_score
FROM
`your-project.population_dynamics___us___domestic.v1_postal_code.embeddings_table` t,
TargetLocation p
WHERE
t.snapshot_date = '2025-10-01' -- You must use the first of the month ('-01')
AND t.geo_name != '90210' -- Exclude the target itself
ORDER BY
similarity_score DESC
LIMIT 20;
4. SQL：联接客户数据
此示例演示了如何通过邮政编码联接，使用行为嵌入来丰富您自己的内部数据（例如“商店效果”表）。
SELECT
store.store_id,
store.postal_code,
store.total_revenue,
embeddings.features AS pdi_vector
FROM
`your-project.internal_data.store_performance` AS store
JOIN
`your-project.population_dynamics___us___domestic.v1_postal_code.embeddings_table` AS embeddings
ON
store.postal_code = embeddings.geo_name
WHERE
embeddings.snapshot_date = '2025-10-01' -- You must use the first of the month ('-01')
5. Python：加载数据以进行机器学习
嵌入以 BigQuery 数组的形式存储。如需在机器学习库中使用这些列，您必须将这些列转换为 NumPy 矩阵。
from google.cloud import bigquery
import numpy as np
import pandas as pd
client = bigquery.Client()
query = """
SELECT
geo_name,
features -- Returns as a list of floats
FROM
`your-project.population_dynamics___us___domestic.v1_postal_code.embeddings_table`
WHERE
snapshot_date = '2025-10-01' -- You must use the first of the month ('-01')
LIMIT 1000
"""
# 1. Load data into DataFrame
df = client.query(query).to_dataframe()
# 2. Convert the 'features' column (Series of Lists) into a Matrix (2D Array)
X_matrix = np.stack(df['features'].values)
print(f"Data Loaded. Matrix Shape: {X_matrix.shape}")
# Output: Data Loaded. Matrix Shape: (1000, 330)
常见问题解答 (FAQ)
我可以访问原始输入数据（例如，特定搜索查询或移动轨迹）吗？
不会。人口动态嵌入是从汇总的、可保护隐私的信号生成的。为确保用户隐私，我们不会提供具体的用户轨迹、个人搜索记录或原始移动模式。这些嵌入内容提供了这些行为的潜在表示，经过优化，可用于建模和预测，而不是原始分析。
您如何选择用于生成嵌入的搜索字词？
我们使用知识图谱 (KG) 实体，而不是原始搜索查询。例如，“taylor swift boyfriend”和“kc tight end”等查询都会映射到同一个底层知识图谱实体（“Travis Kelce”）。这种方法与语言无关，可捕获更广泛的语义类别，并显著增强隐私保护。
向量维度是否可解释（例如，维度 5 是否为“咖啡”）？
不是，向量是潜在表示。由于这些特征是由机器学习模型学习的，因此无法实现从最终向量索引到特定来源输入的简单语义映射或一对一转换。虽然我们知道哪些指数块源自哪些数据集（例如，指数 0-127 代表搜索趋势），但特定指数（例如指数 5）并不对应于单个关键字。相反，它表示模型学习到的复杂抽象特征。
数据集是否包含多边形边界（Shapefile）？
否。该数据集提供邮政编码 (geo_name) 及其关联的地点 ID (geo_id)，但不包含原始多边形几何图形（例如 WKT）。
根据您的使用情形，我们建议您采用以下方法：
- 在 Google 地图上进行可视化：您可以使用 geo_id 中提供的地点 ID，通过数据驱动型样式直接在地图上设置边界的样式并渲染边界。虽然这些边界非常适合用于直观显示，但无法导出为原始几何文件。
- 对于空间联接和分析：如果您需要原始空间多边形，建议您使用地理名称邮政编码将此数据集与公共边界数据集（例如 BigQuery 公共数据集中的数据集）联接起来。
嵌入数据集的时间窗口是什么？
PDI 嵌入内容每月都会更新，每个新月份都会附加到数据集中。数据使用 snapshot_date 列（格式为 YYYY-MM-DD）表示，可提供稳定的基准，反映相应月份的位置行为和物理指纹。