Repository navigation
Expand file tree
/
Copy pathsagerec_api.py
More file actions
182 lines (166 loc) · 6.3 KB
/
Copy pathsagerec_api.py
File metadata and controls
182 lines (166 loc) · 6.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
"""FastAPI serving layer for a precomputed SageRec artifact (ADR-009, ADR-010).
Routes:
- ``GET /healthz``
- ``GET /recommend?user_id=&k=&rerank=&n=``
``item_id`` in each row is the zero-based movie id. Already-seen train
positives are excluded. Unknown users return HTTP 404. Invalid query
parameters return HTTP 422. Top-K is exact NumPy (``sagerec_serving``);
FAISS is not required.
``rerank`` defaults to false, which is the ADR-009 retrieval path. When
``rerank=true`` and ``SAGEREC_RERANK_ARTIFACT`` (or ``rerank_path``) is
loaded, stage 1 returns ``n`` candidates and the exported MLP re-ranks them
to ``k``. The service does not train, sample, or download on the request.
This module does not import PyTorch, PyG, or ``graph_sampler``.
"""
from __future__ import annotations
import os
from pathlib import Path
from typing import Any
from fastapi import FastAPI, HTTPException, Query
import sagerec_rerank as rerank
import sagerec_serving as serving
_RERANK_MISSING = (
"rerank=true requires a loaded sagerec_rerank_artifact. Set "
"SAGEREC_RERANK_ARTIFACT or pass rerank_path to create_app. The service "
"does not train a re-ranker on the request path."
)
def create_app(
artifact_path: str | Path | None = None,
rerank_path: str | Path | None = None,
) -> FastAPI:
"""Build an app bound to one serving artifact and an optional re-ranker.
Uvicorn's factory calls this with no arguments and reads
``SAGEREC_SERVING_ARTIFACT`` plus optional ``SAGEREC_RERANK_ARTIFACT``.
Tests pass ``artifact_path`` directly. An explicit artifact path does
not inherit an ambient re-rank env var; pass ``rerank_path`` in tests.
"""
factory_mode = artifact_path is None and rerank_path is None
if artifact_path is None:
artifact_path = os.environ.get("SAGEREC_SERVING_ARTIFACT")
if not artifact_path:
raise serving.ServingError(
"SAGEREC_SERVING_ARTIFACT is not set. Point it at a "
f"{serving.SERVING_SCHEMA} .npz, or pass artifact_path to create_app. "
"The service does not download MovieLens or train a model."
)
index = serving.load_serving_artifact(artifact_path)
if rerank_path is None and factory_mode:
raw_rerank = os.environ.get("SAGEREC_RERANK_ARTIFACT", "").strip()
rerank_path = raw_rerank or None
bundle: rerank.RerankBundle | None = None
if rerank_path:
bundle = rerank.load_rerank_artifact(rerank_path)
rerank.assert_rerank_compatible(
bundle,
num_users=index.num_users,
num_items=index.num_items,
stage1_model=str(index.metadata["model"]),
)
app = FastAPI(
title="SageRec",
version="1",
docs_url=None,
redoc_url=None,
openapi_url=None,
)
@app.get("/healthz")
def healthz() -> dict[str, Any]:
return {
"status": "ok",
"schema": serving.SERVING_SCHEMA,
"schema_version": serving.SERVING_SCHEMA_VERSION,
"model": index.metadata["model"],
"num_users": index.num_users,
"num_items": index.num_items,
"embedding_dim": index.embedding_dim,
"rerank_loaded": bundle is not None,
}
@app.get("/recommend")
def recommend(
user_id: int = Query(
...,
description="Zero-based user id. Unknown ids return 404.",
),
k: int = Query(
serving.DEFAULT_K,
ge=1,
description="Number of unseen items to return (default 10).",
),
rerank_enabled: bool = Query(
False,
alias="rerank",
description=(
"When true, re-rank the stage-1 pool with the loaded MLP. "
"Default false keeps ADR-009 retrieval order."
),
),
n: int | None = Query(
None,
ge=1,
description=(
"Stage-1 candidate count used only when rerank=true. "
"Defaults to 200, or the artifact's stage1_n when that is set."
),
),
) -> dict[str, Any]:
if not rerank_enabled:
try:
rows = serving.recommend_topk(index, user_id, k)
except serving.UnknownUserError as exc:
raise HTTPException(status_code=404, detail=str(exc)) from exc
return {
"user_id": user_id,
"k": k,
"rerank": False,
"recommendations": [
{
"item_id": row.item_id,
"title": row.title,
"score": row.score,
}
for row in rows
],
}
if bundle is None:
raise HTTPException(status_code=422, detail=_RERANK_MISSING)
if n is None:
stage1_n = int(bundle.metadata.get("stage1_n", rerank.DEFAULT_STAGE1_N))
else:
stage1_n = int(n)
if stage1_n < k:
raise HTTPException(
status_code=422,
detail=(
f"n must be >= k when rerank=true so stage 1 can fill the "
f"re-rank pool, got n={stage1_n} k={k}"
),
)
try:
stage1 = serving.recommend_topk(index, user_id, stage1_n)
ordered = rerank.order_candidates(
bundle,
user_id,
[row.item_id for row in stage1],
[row.score for row in stage1],
)
except serving.UnknownUserError as exc:
raise HTTPException(status_code=404, detail=str(exc)) from exc
except rerank.RerankError as exc:
raise HTTPException(status_code=422, detail=str(exc)) from exc
retrieval_by_id = {row.item_id: row.score for row in stage1}
return {
"user_id": user_id,
"k": k,
"rerank": True,
"stage1_n": stage1_n,
"recommendations": [
{
"item_id": item_id,
"title": index.item_titles[item_id],
"score": score,
"retrieval_score": retrieval_by_id[item_id],
}
for item_id, score in ordered[:k]
],
}
return app