搜索API对接指南-05-索引接口（Indexer）.md 25.5 KB
Edit Raw Blame History


搜索API对接指南-05-索引接口（Indexer）
本篇覆盖数据同步/索引构建相关的所有接口（原文第 5 章），用于 external indexer 和 Indexer 服务 的对接。
索引接口
本节内容与 api/routes/indexer.py 中的索引相关服务一致，包含以下接口：


接口
方法
路径
说明


全量重建索引
POST
/indexer/reindex
将指定租户所有 SPU 导入 ES（不删现有索引）


增量索引
POST
/indexer/index
按 SPU ID 列表索引/删除，支持自动检测删除与显式删除


查询文档
POST
/indexer/documents
按 SPU ID 列表查询 ES 文档，不写入 ES


构建 ES 文档（正式）
POST
/indexer/build-docs
由上游提供 MySQL 行数据，返回 ES-ready 文档，不写 ES


构建 ES 文档（测试）
POST
/indexer/build-docs-from-db
由本服务查库并构建文档，仅测试/调试用


内容理解字段生成
POST
/indexer/enrich-content
根据商品标题批量生成 qanchors、enriched_attributes、tags（供微服务组合方式使用）


索引健康检查
GET
/indexer/health
检查索引服务与数据库连接状态


5.0 支撑外部 indexer 的三种方式
本服务对外部 indexer 程序（如 Java 索引系统）提供三种对接方式，可按需选择：


方式
说明
适用场景


1）doc 填充接口
调用 POST /indexer/build-docs 或 POST /indexer/build-docs-from-db，由本服务基于 MySQL 行数据构建完整 ES 文档（含多语言、向量、规格等），不写入 ES，由调用方自行写入。
希望一站式拿到 ES-ready doc，由己方控制写 ES 的时机与索引名。


2）微服务组合
单独调用翻译、向量化、内容理解字段生成等接口，由 indexer 程序自己组装 doc 并写入 ES。翻译与向量化为独立微服务（见第 7 节）；内容理解为 Indexer 服务内接口 POST /indexer/enrich-content。
需要灵活编排、或希望将 LLM/向量等耗时步骤与主链路解耦（如异步补齐 qanchors/tags）。


3）本服务直接写 ES
调用全量索引 POST /indexer/reindex、增量索引 POST /indexer/index（指定 SPU ID 列表），由本服务从 MySQL 拉数并直接写入 ES。
自建运维、联调或不需要由 Java 写 ES 的场景。


方式 1 与 方式 2 下，ES 的写入方均为外部 indexer（或 Java），职责清晰。
方式 3 下，本服务同时负责读库、构建 doc 与写 ES。

5.1 为租户创建索引
为租户创建索引需要两个步骤：


创建索引结构（可选，仅在需要更新 mapping 或在新环境首次创建时执行）


使用脚本创建 ES 索引结构（基于 mappings/search_products.json）
如果索引已存在，会提示用户确认（会删除现有数据）

导入数据（必需）


使用全量索引接口 /indexer/reindex 导入数据


创建索引结构（支持多环境 namespace）：
# 以 UAT 环境为例：
# 1. 准备 UAT 环境的 .env（包含 UAT 的 ES_HOST/DB_HOST 等）
# 2. 设置环境前缀（也可以直接在 .env 中配置）：
export RUNTIME_ENV=uat
export ES_INDEX_NAMESPACE=uat_

# 3. 为 tenant_id=170 创建索引结构
./scripts/create_tenant_index.sh 170


脚本会自动从项目根目录的 .env 文件加载 ES 配置，并根据 ES_INDEX_NAMESPACE 创建：


prod 环境（ES_INDEX_NAMESPACE 为空）：search_products_tenant_170
UAT 环境（ES_INDEX_NAMESPACE=uat_）：uat_search_products_tenant_170


注意事项：


⚠️ 如果索引已存在，脚本会提示确认，确认后会删除现有数据
创建索引后，必须调用 /indexer/reindex 导入数据
如果只是更新数据而不需要修改索引结构，直接使用 /indexer/reindex 即可


5.2 全量索引接口

端点: POST /indexer/reindex
描述: 全量索引，将指定租户的所有SPU数据导入到ES索引（不会删除现有索引）。推荐仅用于自测/运维场景；生产环境下更推荐由 Java 等上游控制调度与写 ES。

请求参数
{
  "tenant_id": "162",
  "batch_size": 500
}


参数
类型
必填
默认值
说明


tenant_id
string
Y
-
租户ID


batch_size
integer
N
500
批量导入大小


响应格式
成功响应（200 OK）（示例，实际 index_name 会带上 tenant 和环境前缀）:
{
  "success": true,
  "total": 1000,
  "indexed": 1000,
  "failed": 0,
  "elapsed_time": 12.34,
  "index_name": "search_products_tenant_162",
  "tenant_id": "162"
}


错误响应:


400 Bad Request: 参数错误
503 Service Unavailable: 服务未初始化

请求示例
全量索引（不会删除现有索引）:
curl -X POST "http://localhost:6004/indexer/reindex" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "162",
    "batch_size": 500
  }'


查看日志:
# 查看API日志（包含索引操作日志）
tail -f logs/api.log

# 或者查看所有日志文件
tail -f logs/*.log


⚠️ 重要提示：如需 创建索引结构，请参考 5.1 为租户创建索引 章节，使用 ./scripts/create_tenant_index.sh <tenant_id>。创建后需要调用 /indexer/reindex 导入数据。


查看索引日志:

索引操作的所有关键信息都会记录到 logs/indexer.log 文件中（JSON 格式），包括：


请求开始和结束时间
租户ID、SPU ID、操作类型
每个SPU的处理状态
ES批量写入结果
成功/失败统计和详细错误信息

# 实时查看索引日志（包含全量和增量索引的所有操作）
tail -f logs/indexer.log

# 使用 grep 查询（简单方式）
# 查看全量索引日志
grep "\"index_type\":\"bulk\"" logs/indexer.log | tail -100

# 查看增量索引日志
grep "\"index_type\":\"incremental\"" logs/indexer.log | tail -100

# 查看特定租户的索引日志
grep "\"tenant_id\":\"162\"" logs/indexer.log | tail -100

# 使用 jq 查询（推荐，更精确的 JSON 查询）
# 安装 jq: sudo apt-get install jq 或 brew install jq

# 查看全量索引日志
cat logs/indexer.log | jq 'select(.index_type == "bulk")' | tail -100

# 查看增量索引日志
cat logs/indexer.log | jq 'select(.index_type == "incremental")' | tail -100

# 查看特定租户的索引日志
cat logs/indexer.log | jq 'select(.tenant_id == "162")' | tail -100

# 查看失败的索引操作
cat logs/indexer.log | jq 'select(.operation == "request_complete" and .failed_count > 0)'

# 查看特定SPU的处理日志
cat logs/indexer.log | jq 'select(.spu_id == "123")'

# 查看最近的索引请求统计
cat logs/indexer.log | jq 'select(.operation == "request_complete") | {timestamp, index_type, tenant_id, total_count, success_count, failed_count, elapsed_time}'

5.3 增量索引接口

端点: POST /indexer/index
描述: 增量索引接口，根据指定的SPU ID列表进行索引，直接将数据写入ES。用于增量更新指定商品。推荐仅作为内部/调试入口；正式对接建议改用 /indexer/build-docs，由上游写 ES。


删除说明：


spu_ids中的SPU：如果数据库deleted=1，自动从ES删除，响应状态为deleted
delete_spu_ids中的SPU：直接删除，响应状态为deleted、not_found或failed

请求参数
{
  "tenant_id": "162",
  "spu_ids": ["123", "456", "789"],
  "delete_spu_ids": ["100", "101"]
}


参数
类型
必填
说明


tenant_id
string
Y
租户ID


spu_ids
array[string]
N
SPU ID列表（1-100个），要索引的SPU。如果为空，则只执行删除操作


delete_spu_ids
array[string]
N
显式指定要删除的SPU ID列表（1-100个），可选。无论数据库状态如何，都会从ES中删除这些SPU


注意：


spu_ids 和 delete_spu_ids 不能同时为空
每个列表最多支持100个SPU ID
如果SPU在spu_ids中且数据库deleted=1，会自动从ES删除（自动检测删除）

响应格式
{
  "spu_ids": [
    {
      "spu_id": "123",
      "status": "indexed"
    },
    {
      "spu_id": "456",
      "status": "deleted"
    },
    {
      "spu_id": "789",
      "status": "failed",
      "msg": "SPU not found (unexpected)"
    }
  ],
  "delete_spu_ids": [
    {
      "spu_id": "100",
      "status": "deleted"
    },
    {
      "spu_id": "101",
      "status": "not_found"
    },
    {
      "spu_id": "102",
      "status": "failed",
      "msg": "Failed to delete from ES: Connection timeout"
    }
  ],
  "total": 6,
  "success_count": 4,
  "failed_count": 2,
  "elapsed_time": 1.23,
  "index_name": "search_products",
  "tenant_id": "162"
}


字段
类型
说明


spu_ids
array
spu_ids对应的响应列表，每个元素包含 spu_id 和 status


spu_ids[].status
string
状态：indexed（已索引）、deleted（已删除，自动检测）、failed（失败）


spu_ids[].msg
string
当status为failed时，包含失败原因（可选）


delete_spu_ids
array
delete_spu_ids对应的响应列表，每个元素包含 spu_id 和 status


delete_spu_ids[].status
string
状态：deleted（已删除）、not_found（ES中不存在）、failed（失败）


delete_spu_ids[].msg
string
当status为failed时，包含失败原因（可选）


total
integer
总处理数量（spu_ids数量 + delete_spu_ids数量）


success_count
integer
成功数量（indexed + deleted + not_found）


failed_count
integer
失败数量


elapsed_time
float
耗时（秒）


index_name
string
索引名称


tenant_id
string
租户ID


状态说明：


spu_ids 的状态：


indexed: SPU已成功索引到ES
deleted: SPU在数据库中被标记为deleted=1，已从ES删除（自动检测）
failed: 处理失败，会包含msg字段说明失败原因

delete_spu_ids 的状态：


deleted: SPU已从ES成功删除
not_found: SPU在ES中不存在（也算成功，可能已经被删除过）
failed: 删除失败，会包含msg字段说明失败原因


请求示例
示例1：普通增量索引（自动检测删除）:
curl -X POST "http://localhost:6004/indexer/index" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "162",
    "spu_ids": ["123", "456", "789"]
  }'


说明：如果SPU 456在数据库中deleted=1，会自动从ES删除，在响应中spu_ids列表里456的状态为deleted。

示例2：显式删除（批量删除）:
curl -X POST "http://localhost:6004/indexer/index" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "162",
    "spu_ids": ["123", "456"],
    "delete_spu_ids": ["100", "101", "102"]
  }'


说明：SPU 100、101、102会被显式删除，无论数据库状态如何。

示例3：仅删除（不索引）:
curl -X POST "http://localhost:6004/indexer/index" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "162",
    "spu_ids": [],
    "delete_spu_ids": ["100", "101"]
  }'


说明：只执行删除操作，不进行索引。

示例4：混合操作（索引+删除）:
curl -X POST "http://localhost:6004/indexer/index" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "162",
    "spu_ids": ["123", "456", "789"],
    "delete_spu_ids": ["100", "101"]
  }'


说明：同时执行索引和删除操作。
日志说明
增量索引操作的所有关键信息都会记录到 logs/indexer.log 文件中（JSON格式），包括：


请求开始和结束时间
每个SPU的处理状态（获取、转换、索引、删除）
ES批量写入结果
成功/失败统计
详细的错误信息


日志查询方式请参考5.1节查看索引日志部分。
5.4 查询文档接口

端点: POST /indexer/documents
描述: 查询文档接口，根据SPU ID列表获取ES文档数据（不写入ES）。用于查看、调试或验证SPU数据。

请求参数
{
  "tenant_id": "162",
  "spu_ids": ["123", "456", "789"]
}


参数
类型
必填
说明


tenant_id
string
Y
租户ID


spu_ids
array[string]
Y
SPU ID列表（1-100个）


响应格式
{
  "success": [
    {
      "spu_id": "123",
      "document": {
        "tenant_id": "162",
        "spu_id": "123",
        "title": {
          "zh": "商品标题"
        },
        ...
      }
    },
    {
      "spu_id": "456",
      "document": {...}
    }
  ],
  "failed": [
    {
      "spu_id": "789",
      "error": "SPU not found or deleted"
    }
  ],
  "total": 3,
  "success_count": 2,
  "failed_count": 1
}


字段
类型
说明


success
array
成功获取的SPU列表，每个元素包含 spu_id 和 document（完整的ES文档数据）


failed
array
失败的SPU列表，每个元素包含 spu_id 和 error（失败原因）


total
integer
总SPU数量


success_count
integer
成功数量


failed_count
integer
失败数量


请求示例
单个SPU查询:
curl -X POST "http://localhost:6004/indexer/documents" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "162",
    "spu_ids": ["123"]
  }'


批量SPU查询:
curl -X POST "http://localhost:6004/indexer/documents" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "162",
    "spu_ids": ["123", "456", "789"]
  }'

与 /indexer/index 的区别


接口
功能
是否写入ES
返回内容


/indexer/documents
查询SPU文档数据
否
返回完整的ES文档数据


/indexer/index
增量索引
是
返回成功/失败列表和统计信息


使用场景：


/indexer/documents：用于查看、调试或验证SPU数据，不修改ES索引
/indexer/index：用于实际的增量索引操作，将更新的SPU数据同步到ES

5.5 索引健康检查接口

端点: GET /indexer/health
描述: 检查索引服务健康状态（与 api/routes/indexer.py 中 indexer_health_check 一致）

响应格式
{
  "status": "available",
  "database": "connected",
  "preloaded_data": {
    "category_mappings": 150
  }
}


字段
类型
说明


status
string
available（服务可用）、unavailable（未初始化）、error（异常）


database
string
数据库连接状态，如 connected 或 disconnected: ...


preloaded_data.category_mappings
integer
已加载的分类映射数量


请求示例
curl -X GET "http://localhost:6004/indexer/health"

5.6 文档构建接口（正式对接推荐）
5.6.1 POST /indexer/build-docs

描述:

基于调用方（通常是 Java 索引程序）提供的 MySQL 行数据 构建 ES 文档（doc），不写入 ES。

由本服务负责“如何构建 doc”（多语言、翻译、向量、规格聚合等），由调用方负责“何时调度 + 如何写 ES”。

请求参数
{
  "tenant_id": "170",
  "items": [
    {
      "spu": { "id": 223167, "tenant_id": 170, "title": "..." },
      "skus": [
        { "id": 3988393, "spu_id": 223167, "price": 25.99, "compare_at_price": 25.99 }
      ],
      "options": []
    }
  ]
}


参数
类型
必填
说明


tenant_id
string
Y
租户 ID


items
array
Y
需构建 doc 的 SPU 列表（每项含 spu、skus、options），单次最多 200 条


spu / skus / options 字段应当直接使用从 shoplazza_product_spu / shoplazza_product_sku / shoplazza_product_option 查询出的行字段。

请求示例（完整 curl）

完整请求体参考 scripts/test_build_docs_api.py 中的 build_sample_request()。

# 单条 SPU 示例（含 spu、skus、options）
curl -X POST "http://localhost:6004/indexer/build-docs" \
  -H "Content-Type: application/json" \
  -d '{
  "tenant_id": "162",
  "items": [
    {
      "spu": {
        "id": 10001,
        "title": "测试T恤 纯棉短袖",
        "brief": "舒适纯棉，多色可选",
        "description": "这是一款适合日常穿着的纯棉T恤，透气吸汗。",
        "vendor": "测试品牌",
        "category": "服装/上衣/T恤",
        "category_id": 100,
        "category_level": 2,
        "category_path": "服装/上衣/T恤",
        "fake_sales": 1280,
        "image_src": "https://oss.essa.cn/98532128-cf8e-456c-9e30-6f2a5ea0c19f.jpg",
        "enriched_tags": ["T恤", "纯棉"],
        "create_time": "2024-01-01T00:00:00Z",
        "update_time": "2024-01-01T00:00:00Z"
      },
      "skus": [
        {
          "id": 20001,
          "spu_id": 10001,
          "price": 99.0,
          "compare_at_price": 129.0,
          "sku": "SKU-TSHIRT-001",
          "inventory_quantity": 50,
          "option1": "黑色",
          "option2": "M",
          "option3": null
        },
        {
          "id": 20002,
          "spu_id": 10001,
          "price": 99.0,
          "compare_at_price": 129.0,
          "sku": "SKU-TSHIRT-002",
          "inventory_quantity": 30,
          "option1": "白色",
          "option2": "L",
          "option3": null
        }
      ],
      "options": [
        {"id": 1, "position": 1, "name": "颜色"},
        {"id": 2, "position": 2, "name": "尺码"}
      ]
    }
  ]
}'


生产环境替换 localhost:6004 为实际 Indexer 地址，如 http://43.166.252.75:6004。
响应示例（节选）
{
  "tenant_id": "170",
  "docs": [
    {
      "tenant_id": "170",
      "spu_id": "223167",
      "title": { "en": "...", "zh": "..." },
      "enriched_tags": ["Floerns", "Clothing", "Shoes & Jewelry"],
      "skus": [
        {
          "sku_id": "3988393",
          "price": 25.99,
          "compare_at_price": 25.99,
          "stock": 100
        }
      ],
      "min_price": 25.99,
      "max_price": 25.99,
      "compare_at_price": 25.99,
      "total_inventory": 100,
      "title_embedding": [/* 1024 维向量 */]
      // 其余字段与 mappings/search_products.json 一致
    }
  ],
  "total": 1,
  "success_count": 1,
  "failed_count": 0,
  "failed": []
}


字段
类型
说明


tenant_id
string
租户 ID


docs
array
构建成功的 ES 文档列表，与 mappings/search_products.json 一致


total
integer
请求的 items 总数


success_count
integer
成功构建数量


failed_count
integer
失败数量


failed
array
失败项列表，每项含 spu_id、error


使用建议

生产环境推荐流程：


Java 根据业务逻辑决定哪些 SPU 需要（全量/增量）处理；
Java 从 MySQL 查询 SPU/SKU/Option 行，拼成 items；
调用 /indexer/build-docs 获取 ES-ready docs；
Java 使用自己的 ES 客户端写入 search_products_tenant_{tenant_id}。


5.7 文档构建接口（测试 / 自测）
5.7.1 POST /indexer/build-docs-from-db

描述:

仅用于测试/调试：调用方只提供 tenant_id 和 spu_ids，由 indexer 服务内部从 MySQL 查询 SPU/SKU/Option，然后调用与 /indexer/build-docs 相同的文档构建逻辑，返回 ES-ready doc。生产环境请使用 /indexer/build-docs，由上游查库并写 ES。

请求参数
{
  "tenant_id": "170",
  "spu_ids": ["223167", "223168"]
}


参数
类型
必填
说明


tenant_id
string
Y
租户 ID


spu_ids
array[string]
Y
SPU ID 列表，单次最多 200 个


响应格式
与 /indexer/build-docs 相同：tenant_id、docs、total、success_count、failed_count、failed。
请求示例
curl -X POST "http://127.0.0.1:6004/indexer/build-docs-from-db" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "170", "spu_ids": ["223167"]}'


返回结构与 /indexer/build-docs 相同，可直接用于对比 ES 实际文档或调试字段映射问题。
5.8 内容理解字段生成接口

端点: POST /indexer/enrich-content
描述: 根据商品内容信息批量生成 qanchors（锚文本）、enriched_attributes（语义属性）、enriched_tags（细分标签），供外部 indexer 在「微服务组合」方式下自行拼装 doc 时使用。请求以 items[] 传入商品内容字段（必填/可选见下表）。接口只暴露商品内容输入，语言选择、分析维度与最终字段结构统一由 indexer.product_enrich 内部决定；当前返回结果与 search_products mapping 保持一致。单次请求在线程池中执行，避免阻塞其他接口。

请求参数
{
  "tenant_id": "170",
  "items": [
    {
      "spu_id": "223167",
      "title": "纯棉短袖T恤 夏季男装",
      "brief": "夏季透气纯棉短袖，舒适亲肤",
      "description": "100%棉，圆领版型，适合日常通勤与休闲穿搭。",
      "image_url": "https://example.com/images/223167.jpg"
    },
    {
      "spu_id": "223168",
      "title": "12PCS Dolls with Bottles",
      "image_url": "https://example.com/images/223168.jpg"
    }
  ]
}


参数
类型
必填
默认值
说明


tenant_id
string
Y
-
租户 ID。目前仅用于记录日志，不产生实际作用


items
array
Y
-
待分析列表；单次最多 50 条


items[] 字段说明：


字段
类型
必填
说明


spu_id
string
Y
SPU ID，用于回填结果；目前仅用于记录日志，不产生实际作用


title
string
Y
商品标题


image_url
string
N
商品主图 URL；当前会参与内容缓存键，后续可用于图像/多模态内容理解


brief
string
N
商品简介/短描述；当前会参与内容缓存键


description
string
N
商品详情/长描述；当前会参与内容缓存键


缓存说明：


内容缓存键仅由 target_lang + items[] 中会影响内容理解结果的输入文本构成，目前包括：title、brief、description、image_url 的规范化内容 hash。
tenant_id、spu_id 只用于请求归属与结果回填，不参与缓存键。
因此，输入内容不变时可跨请求直接命中缓存；任一输入字段变化时，会自然落到新的缓存 key。


语言说明：


接口不接受语言控制参数。
返回哪些语言、返回哪些语义维度，统一由 indexer.product_enrich 内部逻辑决定。
当前为了与 search_products mapping 对齐，返回结果只包含核心索引语言 zh、en。


批量请求建议：


全量：强烈建议 尽可能 20 个 SPU/doc 攒成一个批次后再请求一次。
增量：可按时效要求设置时间窗口（例如 5 分钟），在窗口内尽可能攒到 20 个；达到 20 或窗口到期就发送一次请求。
允许超过20，服务内部会拆分成小批次逐个处理。也允许小于20，但是将造成费用和耗时的成本上升，特别是每次请求一个doc的情况。

响应格式
{
  "tenant_id": "170",
  "total": 2,
  "results": [
    {
      "spu_id": "223167",
      "qanchors": {
        "zh": ["短袖T恤", "纯棉", "男装", "夏季"],
        "en": ["cotton t-shirt", "short sleeve", "men", "summer"]
      },
      "enriched_tags": {
        "zh": ["纯棉", "短袖", "男装"],
        "en": ["cotton", "short sleeve", "men"]
      },
      "enriched_attributes": [
        { "name": "enriched_tags", "value": { "zh": "纯棉" } },
        { "name": "usage_scene", "value": { "zh": "日常" } },
        { "name": "enriched_tags", "value": { "en": "cotton" } }
      ]
    },
    {
      "spu_id": "223168",
      "qanchors": {
        "en": ["dolls", "toys", "12pcs"]
      },
      "enriched_tags": {
        "en": ["dolls", "toys"]
      },
      "enriched_attributes": []
    }
  ]
}


字段
类型
说明


results
array
与请求 items 一一对应，每项含 spu_id、qanchors、enriched_attributes、enriched_tags


results[].qanchors
object
与 ES qanchors 字段同结构，按语言键返回短语数组


results[].enriched_tags
object
与 ES enriched_tags 字段同结构，按语言键返回标签数组


results[].enriched_attributes
array
与 ES enriched_attributes nested 字段同结构，每项为 { "name", "value": { "zh"?: "...", "en"?: "..." } }


results[].error
string
若该条处理失败（如 LLM 异常），会在此字段返回错误信息


错误响应:


400: items 为空或超过 50 条
503: 未配置 DASHSCOPE_API_KEY，内容理解服务不可用

请求示例
curl -X POST "http://localhost:6004/indexer/enrich-content" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "170",
    "items": [
      {
        "spu_id": "223167",
        "title": "纯棉短袖T恤 夏季男装夏季男装",
        "brief": "夏季透气纯棉短袖，舒适亲肤",
        "description": "100%棉，圆领版型，适合日常通勤与休闲穿搭。",
        "image_url": "https://example.com/images/223167.jpg"
      }
    ]
  }'