# 快速开始

我们可以使用 pairecmd 快速创建项目。下载地址：

[linux 版本](http://pai-rec-public.oss-cn-shanghai.aliyuncs.com/command/bin/pairecmd)

[mac 版本](http://pai-rec-public.oss-cn-shanghai.aliyuncs.com/command/bin/pairecmdmac)

[window 版本](http://pai-rec-public.oss-cn-shanghai.aliyuncs.com/command/bin/pairecmdwin)

下载之后，在类 *nix 系统，需要设置下可执行文件。 `chmod +x pairecmd`

### 创建项目

 以创建项目名称 pairec-demo 举例，执行命令后，会在当前目录生成 pairec-demo 目录，里面包含项目代码。 

```bash
./pairecmdmac project --name pairec-demo
```

生成的目录结构如下

```
pairec-demo
├── Makefile
├── conf
│   └── config.json.production
├── docker
│   └── Dockerfile
├── go.mod
└── src
    ├── controller
    │   └── feed.go
    └── main.go
```

### 编译打包项目

项目里提供了 Makefile 文件， 如果要编译的话，直接运行

```bash
make && make build
```

如果遇到错误的话，可以先执行 

```bash
go mod tidy
```

如果要打包成镜像的话，可以

```bash
make release
```

可以结合实际情况来修改 Makefile 文件。



### 运行项目

可以进入到 pairec-demo， 里面可以创建 log 目录，可以把服务的log 打到里面。 

 config 传入配置文件路径，log_dir 指定日志目录

```bash
go run src/main.go --config=conf/config.json.production --log_dir=./log
```

如果使用配置的热加载功能，可以参考[这里](http://pai-vision-data-hz.oss-cn-zhangjiakou.aliyuncs.com/pairec/docs/pairec/html/tool/pairec_config.html)。

Config 具体的配置可以参考配置说明模块。



###  接口测试

在生成的项目中，本身已经实现了一个推荐接口，具体实现可以参考 controller/feed.go 。 接口定义如下。

#### 接口名称

/api/rec/feed

#### 请求参数

| 参数名称  | 参数说明                 | 类型       | 是否必须 | 用例                                                         |
| --------- | ------------------------ | ---------- | -------- | ------------------------------------------------------------ |
| uid       | 用户id                   | string     | 是       | "1000079"                                                    |
| size      | 获取item数量             | integer    | 是       | 10                                                           |
| scene_id  | 场景id                   | String     | 是       | home_feed                                                    |
| features  | 上下文特征               | json map   | 否       | {"age":20, "sex":"male"}                                     |
| item_id   | 相似性推荐传入的物品ID   | string     | 否       | 248791390                                                    |
| item_list | 自定义的召回传入列表     | json array | 否       | [{"item_id":"1111", "score":1},{"item_id":"222", "score":0.95}] |
| debug     | debug 用，打印更多的日志 | bool       | 否       | true                                                         |

当有一批召回的数据，希望通过接口传递进来，可以赋值给 item_list。 item_list 是一个数组，每个 item 是 map object ，item 中必须有 item_id 字段，表示物品的ID。其余都是可选的。 item 中如果包含 score 字段，会当成召回得分处理。其余字段当成 item 属性进行处理。

#### 接口返回

| 名称          | 说明                                    | 类型       | 示例                                                         |
| ------------- | --------------------------------------- | ---------- | ------------------------------------------------------------ |
| code          | 接口返回业务码                          | int        | 200                                                          |
| msg           | 业务信息                                | string     | success                                                      |
| request_id    | 请求的唯一标识                          | string     | e332fe9c-7d99-45a8-a047-bc7ec33d07f6                         |
| size          | 返回的推荐条目数量                      | int        | 10                                                           |
| experiment_id | 实验ID 标识, 没有对接 AB 实验，返回为空 | string     | ER2_L1#EG1#E2                                                |
| items         | 返回推荐条目的列表                      | json array | [{"item_id":"248791390","score":0.9991594902203332,"retrieve_id":"mock_recall"}] |

items 条目具体说明如下

| 名称        | 说明         | 类型   | 示例         |
| ----------- | ------------ | ------ | ------------ |
| item_id     | 推荐物品ID   | string | 3v5RE7417j7R |
| retrieve_id | 召回源ID标识 | string | u2i_recall   |
| score       | 推荐得分     | float  | 0.45         |

#### 错误码说明

| 错误码 | 说明                                | msg                                              |
| ------ | ----------------------------------- | ------------------------------------------------ |
| 200    | 接口正常                            | success                                          |
| 299    | 返回的数量不足                      | items size not enough                            |
| 400    | 参数错误，不同的情况， msg 说明不同 | uid not empty 或者nexpected end of JSON input 等 |
| 500    | 服务器错误, 以 HTTP 错误码形式返回  |                                                  |

#### 请求样例

```
curl -v http://host/api/rec/feed -d '{"uid":"76295990", "size":10, "scene_id":"home_feed"}'
```

#### 返回数据

```
{
    "code":200,
    "msg":"success",
    "request_id":"e332fe9c-7d99-45a8-a047-bc7ec33d07f6",
    "size":10,
    "experiment_id":"",
    "items":[
          {
            "item_id":"248791390",
            "score":0.9991594902203332,
            "retrieve_id":"mock_recall"
          },
				...
    ]
}
```