API de callback - : Central de Documentação do Alibaba Cloud

A API de callback integrada do PAI-Rec captura parâmetros de solicitação, features de usuário e features de item no momento exato de cada solicitação de recomendação. Use esses logs para análise de dados, treinamento offline de modelos ou aprendizado online.

Métodos offline — como a associação de features por janelas de tempo — são pouco confiáveis porque a latência entre os links do sistema é difícil de estimar, o que causa vazamento de features. A API de callback resolve esse problema ao registrar as features na source: quando a solicitação de recomendação chega ao serviço, o sistema registra o ID da solicitação, as features de usuário e as features de item em uma fila de mensagens (DataHub ou Kafka) e sincroniza os dados com o MaxCompute (ODPS).

Callback API flow diagram

Pré-requisitos

Antes de começar, verifique se você tem:

Uma implantação do PAI-Rec com o mecanismo DPI configurado
Um projeto DataHub e a URL do endpoint da sua fonte de dados
(Opcional) Um modelo EasyRec, caso seu fluxo de callback use features geradas por modelo

Referência da API

Endpoint

POST /api/callback

Parâmetros da solicitação

Parâmetro	Tipo	Obrigatório	Descrição	Restrições	Exemplo
`scene_id`	string	Sim	Nome da cena para registro de dados	—	`homepage`
`uid`	string	Sim	ID de registro do usuário	—	`85578510`
`request_id`	string	Sim	Identificador exclusivo da solicitação de recomendação	—	`d9cb1c8d***`
`item_list`	json list	Sim	Lista de IDs dos itens recomendados	Cada item deve incluir `item_id`	`[{"item_id":"99886867"}, {"item_id":"99888623"}]`
`features`	json string	Não	Features de usuário no momento da solicitação	String JSON válida	`{"age":25, "city":"beijing"}`
`request_info`	json string	Não	Informações adicionais da solicitação	String JSON válida	`{"recom_id":"12334234"}`

Exemplo de solicitação

curl 'http://host/api/callback' \
  -d '{"uid":"84603208","request_id":"d9cb1c8d-4d3f-491b-9ea3-380481dabde3","scene_id":"homepage","features":{"age":25, "city":"beijing"},"item_list":[{"item_id":"113939841"},{"item_id":"113764910"}],"request_info":{"recom_id":"1111111"}}'

Resposta

{
  "code": 200,
  "msg": "success"
}

Campo	Tipo	Descrição
`code`	integer	Código de status HTTP. `200` indica sucesso.
`msg`	string	Mensagem de status. `success` indica que o callback foi registrado.

Configure o callback

A configuração do callback tem duas partes: o bloco CallBackConfs, que define o comportamento de registro em log, e o bloco DatahubConfs, que define o destino de gravação dos dados.

CallBackConfs

"CallBackConfs": {
  "home_feed": {
    "DataSource": {
      "Name": "pairec_callback_dh",
      "Type": "datahub"
    },
    "RankConf": {
      "RankAlgoList": [
        "ali_rnk_v2_woid_callback_public_v2"
      ],
      "ContextFeatures": [
        "none"
      ],
      "Processor": "EasyRec"
    },
    "RawFeatures": false,
    "RawFeaturesRate": 0,
    "ItemSize": 100,
    "ItemSizeRate": 10,
    "UseUserFeatures": true
  }
}

Parâmetro	Descrição	Padrão	Restrições
`home_feed` (nome da cena)	Cena para registro de dados	—	Deve corresponder a um nome de cena em `SceneConfs`
`DataSource.Type`	Tipo da fila de mensagens	—	Atualmente, apenas `datahub` é suportado
`DataSource.Name`	Nome da fonte de dados do DataHub	—	Deve corresponder a uma chave em `DatahubConfs`
`RankConf`	Configuração do modelo, idêntica à configuração do mecanismo DPI	—	Omita este campo se não houver uso de features geradas por modelo
`RawFeatures`	Defina se o sistema deve registrar as features brutas de item do modelo EasyRec	`false`	Defina como `true` para ative; exige também a definição de `RawFeaturesRate`
`RawFeaturesRate`	Taxa de amostragem para features brutas	`0`	Inteiro de `0` a `100`. Tem efeito apenas quando `RawFeatures` é `true`.
`ItemSize`	Número máximo de itens a processar por callback	Todos os itens do fluxo de recomendação	O sistema trunca os itens para os primeiros `ItemSize` antes da amostragem
`ItemSizeRate`	Taxa de amostragem aplicada após o truncamento por `ItemSize`	—	Inteiro de `1` a `100`. Se tanto `ItemSize` quanto `ItemSizeRate` estiverem definidos, o sistema primeiro trunca para `ItemSize` itens e depois amostra por `ItemSizeRate`.
`UseUserFeatures`	Defina se o sistema deve usar as features de usuário do fluxo de recomendação quando `AutoInvokeCallBack` está ativado	—	Quando definido como `true`, não é necessária uma recuperação separada de features de usuário em `FeatureConfs` para o fluxo de callback

DatahubConfs

O PAI-Rec cria automaticamente o tópico do DataHub com base no nome e no esquema fornecidos. Não é necessário criar o tópico manualmente.

"DatahubConfs": {
  "pairec_callback_dh": {
    "Endpoint": "http://dh-cn-hangzhou-int-vpc.aliyuncs.com",
    "ProjectName": "${ProjectName}",
    "TopicName": "pairec_callback_log",
    "Schemas": [
      {"Field": "request_id",        "Type": "string"},
      {"Field": "module",            "Type": "string"},
      {"Field": "scene",             "Type": "string"},
      {"Field": "request_time",      "Type": "integer"},
      {"Field": "user_features",     "Type": "string"},
      {"Field": "item_features",     "Type": "string"},
      {"Field": "request_info",      "Type": "string"},
      {"Field": "user_id",           "Type": "string"},
      {"Field": "item_id",           "Type": "string"},
      {"Field": "raw_features",      "Type": "string"},
      {"Field": "generate_features", "Type": "string"},
      {"Field": "context_features",  "Type": "string"}
    ]
  }
}

Substitua ${ProjectName} pelo nome do seu projeto DataHub.

Configuração de carregamento de features

O carregamento de features para o fluxo de callback segue a mesma estrutura da configuração de features padrão. A única diferença é o alias da cena: use {scene_name}_callback como nome da cena em FeatureConfs. Por exemplo, para a cena home_feed, use home_feed_callback.

"FeatureConfs": {
  "home_feed_callback": {
    "AsynLoadFeature": true,
    "FeatureLoadConfs": [
      {
        "FeatureDaoConf": {
          "AdapterType": "hologres",
          "HologresName": "pairec-holo",
          "FeatureKey": "user:uid",
          "UserFeatureKeyName": "client_str",
          "HologresTableName": "dwd_ali_user_all_feature_v2_holo",
          "UserSelectFields": "*",
          "FeatureStore": "user"
        },
        "Features": [
          {
            "FeatureType": "new_feature",
            "FeatureName": "day_h",
            "Normalizer": "hour_in_day",
            "FeatureStore": "user"
          },
          {
            "FeatureType": "new_feature",
            "FeatureName": "week_day",
            "Normalizer": "weekday",
            "FeatureStore": "user"
          },
          {
            "FeatureType": "new_feature",
            "FeatureName": "rand_int_v",
            "Normalizer": "random",
            "FeatureStore": "user"
          }
        ]
      },
      {
        "FeatureDaoConf": {
          "AdapterType": "hologres",
          "HologresName": "pairec-holo",
          "FeatureKey": "user:uid",
          "UserFeatureKeyName": "client_str",
          "HologresTableName": "dwd_ali_user_table_v3_expo_static_feature_v2_holo",
          "UserSelectFields": "*",
          "FeatureStore": "user"
        }
      }
    ]
  }
}

Formato de log

Cada solicitação de callback contém um ID de usuário e uma lista de itens. Como as features de usuário podem ser extensas, o sistema grava as features de usuário e de item como registros de log separados no mesmo tópico do DataHub, diferenciados pelo campo module.

Log de features de usuário

Campo	Tipo	Descrição
`module`	string	Sempre `"user"` — identifica este registro como features de usuário
`request_id`	string	ID da solicitação de callback
`scene`	string	Nome da cena da solicitação de callback
`request_time`	integer	Timestamp Unix da solicitação
`user_id`	string	ID do usuário
`user_features`	string	Features de usuário em formato de string JSON
`request_info`	string	Informações adicionais da solicitação de callback

Log de features de item

Campo	Tipo	Descrição
`module`	string	Sempre `"item"` — identifica este registro como features de item
`request_id`	string	ID da solicitação de callback
`scene`	string	Nome da cena da solicitação de callback
`request_time`	integer	Timestamp Unix da solicitação
`user_id`	string	ID do usuário
`item_id`	string	ID do item
`item_features`	string	Features de item em formato de string JSON
`raw_features`	string	Features brutas retornadas pelo modelo EasyRec
`generate_features`	string	Saída da Geração de Features (FG) do modelo EasyRec
`context_features`	string	Features de contexto retornadas pelo modelo EasyRec

Ative callback automático de cena

Por padrão, o callback é um serviço separado chamado manualmente após cada solicitação de recomendação. O mecanismo DPI também suporta invocação automática: após a conclusão de uma solicitação de recomendação, o sistema chama o fluxo de callback automaticamente.

Para ative callbacks automáticos, defina AutoInvokeCallBack como true em SceneConfs:

"SceneConfs": {
  "${scene_name}": {
    "default": {
      "RecallNames": [
        "collaborative_filter"
      ],
      "AutoInvokeCallBack": true,
      "AutoInvokeCallBackRate": 100
    }
  }
}

Substitua ${scene_name} pelo nome real da cena, como home_feed.

Parâmetro	Descrição	Padrão	Restrições
`AutoInvokeCallBack`	Defina se o sistema deve chamar o fluxo de callback automaticamente após cada solicitação de recomendação	—	Defina como `true` para ative
`AutoInvokeCallBackRate`	Percentual de solicitações de recomendação que acionam um callback automático	—	Inteiro de `1` a `100`. Se definido como `0` ou omitido, todo o tráfego aciona um callback.

Próximos passos

Configuração de features