4단계는 확정된 취향 프로필에서 검색 문장을 만들고, 임베딩·벡터 검색·랭킹·추천 이유 생성을 차례로 실행한다고 정했다. 검색할 상품을 어떤 데이터로 만들고, 상품과 취향을 어떤 의미로 비교하며, 검색 결과를 모델에 어떤 근거로 넘길지는 정하지 않았다. 5단계는 그 안쪽을 정한다.

니쥬는 문서 질의응답 서비스가 아니다. 외부 문서를 찾아 답변에 붙이는 전통적인 RAG보다, 취향을 검색 표현으로 바꾸고 상품 카탈로그에서 후보를 찾은 뒤 그 근거로 추천 이유를 쓰는 **검색 증강 추천(Retrieval-Augmented Recommendation)**에 가깝다. 따라서 대화와 프로필 추출에는 검색을 붙이지 않고, 리스트 생성 잡의 상품 검색과 추천 이유 생성에만 컨텍스트 보강을 적용한다.

비전·음성·이미지·영상 생성 파이프라인은 서비스 범위에 없다. 상품 이미지는 화면 표시용 URL로 보관하지만 이미지 임베딩이나 Visual RAG에는 사용하지 않는다. 이미지 자체가 추천 품질에 필요하다는 근거가 생기면 별도 실험으로 검토한다.

flowchart LR
    SRC["상품 페이지<br/>크롤링"] --> RAW["수집 원본<br/>출처 · 시각 · 원문 해시"]
    RAW --> CORE["상품 기본 정보<br/>이름 · 카테고리 · 가격 · 링크"]
    RAW --> SEM["의미 속성<br/>특징 · 관심사 · 사용 맥락 · 선물 특성"]
    RAW --> FILTER["필터 속성<br/>알레르기 · 향 · 소재"]

    CORE --> DOC["검색 문서 생성<br/>고정 템플릿"]
    SEM --> DOC
    DOC --> C["content 문서"]
    DOC --> U["usage 문서"]
    DOC --> G["gift 문서"]
    C --> EMB["Upstage Embed 2<br/>1024차원"]
    U --> EMB
    G --> EMB
    EMB --> PG[("PostgreSQL + pgvector")]

flowchart LR
    PI["ProfileItem<br/>'캠핑장에서 핸드드립'"] --> QP["SearchQuery 생성"]

    QP --> QC["content query<br/>휴대용 캠핑 커피 용품"]
    QP --> QU["usage query<br/>캠핑에서 커피를 내려 마실 때 쓰는 제품"]
    QP --> QG["gift query<br/>캠핑과 커피를 좋아하는 사람의 선물"]

    QC -.코사인 유사도.-> PC["product.content"]
    QU -.코사인 유사도.-> PU["product.usage"]
    QG -.코사인 유사도.-> PG["product.gift"]

flowchart LR
    P["확정된 TasteProfile"] --> S["query 역할 항목 선별"]
    S --> Q["구조화 SearchQuery<br/>최대 6개"]
    Q --> E["쿼리 임베딩<br/>배치 1회"]
    E --> V["pgvector 검색<br/>하드필터 포함"]
    V --> M["productId 합집합<br/>matchedSignals 누적"]
    M --> RS["self 유사도 순위"]
    M --> RG["gift 유사도 순위"]
    RS --> DS["다양성 선별<br/>20개"]
    RG --> DG["다양성 선별<br/>20개"]
    DS --> CS["상품 사실 + 매칭 근거"]
    DG --> CG["상품 사실 + 공개 가능한 근거"]
    CS --> L["추천 이유 모델"]
    CG --> L
    L --> OUT["self + gift"]

flowchart LR
    G["골드셋<br/>프로필 · 모드 · 관련 상품 · 금지 상품"] --> B0["B0<br/>content + direct query"]
    G --> E1["E1<br/>content + rewritten query"]
    G --> E2["E2<br/>content·usage + direct query"]
    G --> E3["E3<br/>content·usage·gift + view query"]

    B0 --> C["Recall@K · nDCG@K<br/>금지 위반 · 지연"]
    E1 --> C
    E2 --> C
    E3 --> C
    C --> D["개선된 구성만 채택"]

RAG 도입 전에는 모델이나 외부 검색 API가 알고 있는 상품만 추천할 수 있다. 도입 후에는 AI 서버가 보유한 카탈로그 안에서만 상품을 고르고, 어떤 취향 쿼리가 어떤 상품을 데려왔는지 추적할 수 있다. 최신성은 모델 파라미터가 아니라 카탈로그 배치 주기로 관리한다.

수집처와 수집 방식은 아직 정하지 않았다. API·제휴 피드·크롤링 중 어떤 방법을 쓰더라도 sourceProvider, sourceProductId, sourceUrl, crawledAt을 남긴다. 수집 허용 범위와 리뷰 이용 가능 여부를 확인하기 전에는 원문 장기 보관을 전제로 하지 않는다. 리뷰를 사용할 수 있더라도 필요한 구조화 속성과 요약만 남기고 원문 보관 여부는 별도로 결정한다.

상품 카테고리와 취향 택소노미를 하나로 합치지 않는다.

하나의 상품은 여러 취향 노드에 연결될 수 있다. 티타늄 머그컵은 상품 카테고리로는 캠핑식기 하나지만, 취향으로는 캠핑커피·백패킹·미니멀 장비와 동시에 연결될 수 있다.

TasteNode는 처음부터 닫힌 enum으로 만들지 않는다. L1·L2는 개발자가 시드로 만들고, 매핑되지 않은 취향 표현을 로그에 쌓아 반복되는 값을 후보 노드로 올린다. L3의 전체 범위와 활성화 기준은 초기 카탈로그를 보고 정한다.

크롤링한 상품의 정체성과 화면 표시 값을 보관한다.

CREATE TABLE catalog_product (
    product_id               BIGSERIAL PRIMARY KEY,
    canonical_key           TEXT NOT NULL UNIQUE,
    source_provider         TEXT NOT NULL,
    source_product_id       TEXT NOT NULL,
    source_url              TEXT NOT NULL,
    title                   TEXT NOT NULL,
    brand                   TEXT,
    product_category_id     BIGINT,
    price_krw               INTEGER,
    image_url               TEXT,
    seller_name             TEXT,
    in_stock                BOOLEAN,
    status                  TEXT NOT NULL,
    crawled_at              TIMESTAMPTZ NOT NULL,
    availability_checked_at TIMESTAMPTZ,
    source_content_hash     TEXT NOT NULL,
    UNIQUE (source_provider, source_product_id)
);

canonical_key는 같은 상품이 여러 판매처에서 수집되어도 피드백과 추천 이력이 하나의 내부 상품을 가리키게 하기 위한 키다. 동일 상품 판정 규칙은 수집처가 정해진 뒤 확정한다.

검색 문서를 만들기 위한 구조화 의미다. LLM이 자유문장을 직접 만드는 대신 JSON 스키마로 이 값을 추출한다.

CREATE TABLE product_semantics (
    product_id           BIGINT PRIMARY KEY
                         REFERENCES catalog_product(product_id),
    product_type         TEXT NOT NULL,
    features             TEXT[] NOT NULL DEFAULT '{}',
    matched_interests    TEXT[] NOT NULL DEFAULT '{}',
    usage_contexts       TEXT[] NOT NULL DEFAULT '{}',
    gift_traits          TEXT[] NOT NULL DEFAULT '{}',
    review_summary       TEXT,
    extraction_version   TEXT NOT NULL,
    source_content_hash  TEXT NOT NULL,
    extracted_at         TIMESTAMPTZ NOT NULL
);

source_content_hash가 catalog_product의 현재 값과 다르면 이 파생값은 낡은 것으로 본다. features·usageContexts·giftTraits는 상품 원본 또는 허용된 리뷰에서 근거를 찾을 수 있는 값만 저장한다.

벡터 유사도가 아니라 정확 조건으로 처리할 값이다.

CREATE TABLE product_filter_feature (
    product_id           BIGINT PRIMARY KEY
                         REFERENCES catalog_product(product_id),
    allergens            TEXT[] NOT NULL DEFAULT '{}',
    allergen_status      TEXT NOT NULL,
    materials            TEXT[] NOT NULL DEFAULT '{}',
    scent_level          TEXT NOT NULL,
    needs_size           BOOLEAN,
    needs_install        BOOLEAN,
    is_fragile           BOOLEAN,
    contains_alcohol     BOOLEAN,
    is_consumable        BOOLEAN,
    extraction_version   TEXT NOT NULL,
    verified_at          TIMESTAMPTZ
);

allergenStatus는 verified 또는 unknown이다. 상세 페이지에 알레르기 표기가 없다는 사실을 "알레르기 물질 없음"으로 해석하지 않는다.

온보딩에서 사용자의 알레르기를 받아도 상품에 대응 속성이 없으면 필터는 동작하지 않는다. 상품 알레르기 정보는 상품명이나 카테고리만 보고 LLM이 추측하게 하지 않고, 원본 표기 또는 검수된 데이터에서만 verified로 올린다.

CREATE TABLE taste_node (
    taste_node_id BIGSERIAL PRIMARY KEY,
    node_key      TEXT NOT NULL UNIQUE,
    parent_id     BIGINT REFERENCES taste_node(taste_node_id),
    level         SMALLINT NOT NULL,
    label         TEXT NOT NULL,
    aliases       TEXT[] NOT NULL DEFAULT '{}',
    status        TEXT NOT NULL
);

CREATE TABLE product_taste_node (
    product_id      BIGINT REFERENCES catalog_product(product_id),
    taste_node_id   BIGINT REFERENCES taste_node(taste_node_id),
    relation_type   TEXT NOT NULL,
    confidence      NUMERIC NOT NULL,
    mapping_source  TEXT NOT NULL,
    mapping_version TEXT NOT NULL,
    PRIMARY KEY (product_id, taste_node_id, relation_type)
);

relationType은 content·usage·gift 중 하나다. mappingSource는 manual·rule·llm을 구분한다. 모델이 만든 매핑과 개발자가 확인한 매핑을 같은 신뢰도로 다루지 않는다.

CREATE TABLE embedding_space (
    embedding_space_id      BIGSERIAL PRIMARY KEY,
    model_name              TEXT NOT NULL,
    model_version           TEXT NOT NULL,
    dimensions              INTEGER NOT NULL,
    distance_metric         TEXT NOT NULL,
    document_schema_version TEXT NOT NULL,
    active                  BOOLEAN NOT NULL,
    UNIQUE (model_name, model_version, document_schema_version)
);

상품과 쿼리가 같은 임베딩 모델을 썼다는 것만으로 충분하지 않다. 검색 문서 조립 규칙이 바뀌면 분포도 달라지므로 documentSchemaVersion까지 하나의 임베딩 공간으로 묶는다.

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE product_search_document (
    product_id           BIGINT REFERENCES catalog_product(product_id),
    view_type            TEXT NOT NULL,
    embedding_space_id   BIGINT REFERENCES embedding_space(embedding_space_id),
    document_text        TEXT NOT NULL,
    document_hash        TEXT NOT NULL,
    generator_version    TEXT NOT NULL,
    embedding            VECTOR(1024) NOT NULL,
    embedded_at          TIMESTAMPTZ NOT NULL,
    PRIMARY KEY (product_id, view_type, embedding_space_id)
);

한 상품은 활성 임베딩 공간에서 최대 세 행을 가진다. 임베딩 모델을 바꿀 때 새 embeddingSpaceId로 전체 벡터를 채우고 검증한 뒤 active를 전환한다. 기존 공간을 먼저 덮어쓰지 않는다.

초기 목표는 상품 약 1만 개, 벡터 최대 3종으로 3만 벡터다. 2단계 판단대로 먼저 exact nearest-neighbor 검색을 사용한다. 일반 필터 인덱스를 만들고 실제 검색 p95가 병목이 될 때 HNSW를 비교한다.

CREATE INDEX idx_catalog_product_status_stock
    ON catalog_product (status, in_stock);

CREATE INDEX idx_catalog_product_category
    ON catalog_product (product_category_id);

CREATE INDEX idx_product_filter_allergens
    ON product_filter_feature USING GIN (allergens);

CREATE INDEX idx_product_filter_materials
    ON product_filter_feature USING GIN (materials);

CREATE INDEX idx_search_document_space_view
    ON product_search_document (embedding_space_id, view_type);

HNSW는 기본 설계가 아니라 비교 대상이다.

CREATE INDEX idx_product_search_hnsw
    ON product_search_document
    USING hnsw (embedding vector_cosine_ops);

근사 인덱스 도입 시에는 exact 검색 결과를 기준으로 recall과 필터 적용 후 반환 개수를 비교한다. 하드필터는 항상 SQL WHERE에 남기며, ANN이 후보를 적게 반환하더라도 금지 조건을 완화하지 않는다.

검색 문서는 product_semantics와 상품 사실을 고정된 순서로 조립한다. 없는 값을 채우지 않고, 배열은 정렬과 중복 제거 후 넣는다.

예시 상품은 티타늄 이중벽 캠핑 머그컵이다.

[content]
상품 유형: 캠핑용 머그컵
카테고리: 캠핑식기
소재: 티타늄
특징: 경량, 보온, 내구성
관련 관심사: 캠핑, 커피, 백패킹

[usage]
사용 상황: 캠핑장에서 커피나 차를 마실 때
사용 상황: 무게를 줄여야 하는 야외 활동
관련 관심사: 캠핑커피, 백패킹

[gift]
어울리는 대상: 캠핑과 커피를 즐기는 사람
선물 특성: 오래 사용할 수 있는 장비, 실용적인 취미용품
선택 위험: 사이즈 선택 없음, 설치 없음

content는 필수다. usage·gift는 해당 구조화 값이 없으면 벡터를 만들지 않는다. 빈 문서를 억지로 임베딩하면 의미 없는 벡터가 검색된다.

검색 문장은 문자열 배열이 아니라 출처와 목적을 가진 객체다.

{
  "queryId": "q_12",
  "sourceSignalKey": "hobbies:캠핑장에서-핸드드립:2026-09-02T14:32:00Z",
  "sourceField": "hobbies",
  "sourceValue": "캠핑장에서 핸드드립을 즐김",
  "mode": "both",
  "intentType": "both",
  "viewType": "usage",
  "queryText": "캠핑장에서 핸드드립 커피를 만들고 마실 때 사용하는 제품",
  "tasteNodeIds": ["outdoor.camping.camping_coffee"],
  "strategy": "direct",
  "weight": 0.91,
  "hardFilters": {
    "allergens": [],
    "excludeStrongScent": true,
    "excludeProductIds": []
  }
}

하드필터를 queryText에 섞지 않는다.

나쁜 예
향이 강하지 않고 견과류가 없으며 캠핑에서 커피를 마실 때 좋은 선물

좋은 예
queryText  = 캠핑에서 커피를 즐기는 사람에게 어울리는 선물
hardFilter = 강한 향 제외 · 견과류 알레르기 제외

검색문 재작성 모델은 hardFilters, sourceValue, confidence를 바꿀 권한이 없다. 모델은 queryText·viewType·tasteNodeIds 후보만 구조화 출력하고, 서버가 원본 프로필에서 나머지를 다시 채운다. tasteNodeIds도 현재 활성 노드와 원본 taxonomyPath 범위를 벗어나면 버린다.

세 처리는 모두 자연어를 다루지만 발생 시점과 변경할 수 있는 값이 다르다. 하나의 "재작성"으로 묶으면 사용자가 거부한 취향을 검색 단계에서 다시 넣거나, 결과 수를 채우려고 안전 조건을 완화할 수 있다.

프로필 정정은 검색 품질 문제가 아니다. 사용자가 분석 결과에서 항목을 삭제·수정·추가하면 프로필 추출 단계가 새 버전을 만들고 다시 확인받는다. 이 문서의 검색 파이프라인은 사용자가 확정한 최신 프로필만 입력으로 받으며, 거부된 값을 동의어나 유사 취향으로 바꾸어 되살리지 않는다. 개인화된 취향 분석 자체를 원하지 않는 경우에는 프로필을 만들지 않으며, 비개인화 목록을 제공할지는 별도 제품 정책으로 정한다.

검색 쿼리 생성·확장은 확정된 취향의 의미를 바꾸지 않고 상품 문서와 비교하기 좋은 표현으로 투영하는 전처리다. 예를 들어 "주말에 밖에서 커피를 마신다"를 "야외에서 커피를 만들고 마실 때 사용하는 제품"으로 바꿀 수 있지만, 사용자에게 없던 등산 취향이나 선물 의도를 추가할 수는 없다.

검색 부족 폴백은 다음 순서로 수행한다.

1. direct로 검색한다.
2. 결과가 부족하면 같은 TasteNode의 활성 별칭을 사용한 taxonomy_expand로 다시 검색한다.
3. 그래도 부족하면 원본 신호와 서버 소유 필드를 고정한 llm_rewrite로 다시 검색한다. 이 단계는 E1과 금지 위반 평가를 통과한 경우에만 운영에서 사용한다.
4. 각 시도의 후보를 productId로 합치고 중복을 제거한 뒤 동일한 최소 유사도와 하드필터를 적용한다.
5. 끝까지 부족하면 관련 없는 상품으로 20개를 채우지 않고 통과한 상품만 반환한다. 후보가 없으면 items: []와 emptyReason을 반환한다.

폴백 쿼리는 원래 쿼리를 대체하는 동일 신호의 다른 표현이며 쿼리 수를 무한히 늘리는 수단이 아니다. 부족이 발생한 tasteNodeId, 필터 통과 수, 최소 유사도 통과 수를 카탈로그 커버리지 로그에 남겨 다음 상품군 수집 근거로 사용한다.

최초 구현은 direct로 기준선을 만든다. 4단계가 배치한 검색문 재작성 모델은 llm_rewrite 실험에 사용한다. 골드셋에서 direct보다 검색 품질이 높고 금지 위반이 늘지 않을 때만 기본 전략으로 전환한다.

프로필의 query 역할 항목은 최대 12개지만 파생 쿼리는 초기 maxQueries = 6으로 제한한다. 확신도만으로 자르면 한 모드의 신호가 사라질 수 있으므로 다음 순서로 고른다.

1. self에만 유효한 신호 중 가장 높은 항목
2. gift에만 유효한 신호 중 가장 높은 항목
3. 두 모드에 유효한 신호
4. 남은 슬롯을 확신도 순으로 채움

해당 신호가 없는 단계는 건너뛴다. 같은 sourceSignalKey와 viewType 조합은 하나만 만든다. 문장만 조금 다른 쿼리를 여러 개 만들어 후보 수를 부풀리지 않는다.

mode는 모델이 아니라 서버가 intentType과 필드에서 파생한다.

한 항목이 여러 view에 걸칠 수 있어도 최초 검색은 가장 직접적인 view 하나만 사용한다. 다중 view 팬아웃은 골드셋에서 recall 부족이 확인될 때 추가한다.

카탈로그 배치는 사용자 요청과 무관하게 batch에서 돈다.

flowchart LR
    C["① 상품 크롤링"] --> N["② 식별·정규화<br/>중복 판정"]
    N --> X["③ 의미·필터 속성 추출<br/>구조화 출력"]
    X --> V["④ 근거·스키마 검증"]
    V --> T["⑤ 검색 문서 렌더링<br/>content·usage·gift"]
    T --> E["⑥ 임베딩 배치"]
    E --> W["⑦ PostgreSQL 저장"]
    W --> Q["⑧ 골드셋 검색 회귀"]

    V -.검증 실패.-> H["검수 대기"]
    Q -.회귀.-> B["활성 공간 전환 중단"]

파생값은 원본보다 먼저 활성화하지 않는다. 상품 행을 먼저 저장하고, 필수 content 문서와 벡터가 준비된 상품만 추천 검색의 active 대상으로 둔다.

{
  "productType": "티타늄 캠핑 머그컵",
  "features": ["경량", "이중벽", "보온"],
  "matchedInterests": ["캠핑", "커피", "백패킹"],
  "usageContexts": [
    "캠핑장에서 커피나 차를 마실 때",
    "무게를 줄여야 하는 야외 활동"
  ],
  "giftTraits": [
    "오래 사용할 수 있는 취미 장비",
    "사이즈 선택이 필요 없는 선물"
  ],
  "filters": {
    "allergens": [],
    "allergenStatus": "unknown",
    "materials": ["티타늄"],
    "scentLevel": "none",
    "needsSize": false,
    "needsInstall": false,
    "containsAlcohol": false,
    "isConsumable": false
  }
}

JSON 스키마 준수는 의미 정확성을 보장하지 않는다. 추출 모델과 프롬프트는 필드별 정확도와 원본 근거 일치율로 검증한다. 특히 알레르기·주류 여부 같은 안전 필드는 모델 출력만으로 verified가 되지 않는다.

하드필터를 적용한 상품 중에서 쿼리와 가까운 검색 문서를 찾는다.

SELECT
    p.product_id,
    p.title,
    d.view_type,
    1 - (d.embedding <=> :query_embedding) AS similarity
FROM product_search_document AS d
JOIN catalog_product AS p
  ON p.product_id = d.product_id
JOIN product_filter_feature AS f
  ON f.product_id = p.product_id
WHERE d.embedding_space_id = :embedding_space_id
  AND d.view_type = :view_type
  AND p.status = 'active'
  AND p.in_stock = TRUE
  AND p.product_id <> ALL(:exclude_product_ids)
  AND (
      cardinality(:user_allergens) = 0
      OR (
          f.allergen_status = 'verified'
          AND NOT (f.allergens && :user_allergens)
      )
  )
  AND (
      :exclude_strong_scent = FALSE
      OR f.scent_level <> 'strong'
  )
ORDER BY d.embedding <=> :query_embedding
LIMIT :top_k;

topK의 초기값은 쿼리당 80으로 둔다. 최대 6개 쿼리에서 중복을 제거하면 4단계의 목표 후보 300~500개에 접근한다는 가정이다. 실제 중복률과 골드셋 recall을 측정한 뒤 조정하며, 80 자체를 제품 요구사항으로 고정하지 않는다.

같은 상품이 여러 쿼리에 걸리면 하나만 남기되 근거는 버리지 않는다.

def merge_candidates(matches: list[VectorMatch]) -> dict[str, Candidate]:
    candidates = {}
    for match in matches:
        candidate = candidates.setdefault(
            match.product_id,
            Candidate(product=match.product, matched_signals=[]),
        )
        candidate.matched_signals.append(
            MatchedSignal(
                query_id=match.query_id,
                source_signal_key=match.source_signal_key,
                view_type=match.view_type,
                similarity=match.similarity,
                confidence=match.query_weight,
            )
        )
    return candidates

초기 랭킹은 사용자가 정한 대로 벡터 유사도를 중심으로 둔다. 별도의 판매량·리뷰·학습 랭커를 이 단계에 추가하지 않는다.

matchScore = cosineSimilarity × ProfileItem.confidence

selfScore = self 또는 both 쿼리에서 얻은 matchScore의 최댓값
giftScore = gift 또는 both 쿼리에서 얻은 matchScore의 최댓값

여러 취향에 동시에 걸린 횟수는 동점 정렬에만 사용한다. 아직 가중치로 더하지 않는다. 근거가 없는 임의 계수가 유사도보다 결과를 더 크게 바꾸는 것을 막기 위해서다.

def rank(candidate: Candidate, mode: str) -> tuple[float, int]:
    eligible = [
        signal for signal in candidate.matched_signals
        if signal.mode in (mode, "both")
    ]
    if not eligible:
        return (0.0, 0)

    score = max(s.similarity * s.confidence for s in eligible)
    return (score, len(eligible))

취향 항목이 N개라고 20 / N개를 먼저 배정하지 않는다. 다음 순서로 선별한다.

1. 모드별 점수가 있는 후보를 점수 내림차순으로 정렬한다.
2. 각 유효 쿼리의 최고 점수 상품이 최소 한 번 검토되도록 1차 순회한다.
3. 같은 상품을 productId로 중복 제거한다.
4. 남은 슬롯은 전체 점수 순으로 채운다.
5. 한 쿼리나 한 상품 카테고리에 결과가 과도하게 몰리면 다양성 상한을 적용한다.
6. 정확한 상한은 골드셋의 relevance와 다양성 지표를 함께 보고 확정한다.

self와 gift는 같은 후보 풀을 공유하지만 다른 쿼리 집합으로 점수를 계산한다. 두 리스트 사이의 상품 중복은 허용한다. 본인에게 필요하면서 선물로도 받고 싶은 상품이 존재하기 때문이다.

결과 부족은 앞의 검색 부족 폴백으로 처리한다. 폴백에서도 안전 필터, 최소 유사도, 원본 취향의 의미를 완화하지 않는다. 온디맨드 상품 수집은 이번 초안의 범위에서 제외하며, 폴백 뒤에도 후보가 없으면 기존 계약대로 items: []와 emptyReason을 반환한다.

추천 이유 모델은 상품을 선택하지 않는다. 최종 상품과 검색 근거를 자연어로 렌더링한다.

{
  "mode": "gift",
  "query": {
    "queryId": "q_12",
    "viewType": "usage",
    "tasteNodeLabels": ["캠핑커피"]
  },
  "product": {
    "productId": "p_1234",
    "title": "티타늄 더블월 머그컵 350ml",
    "category": "캠핑식기",
    "brand": "Example",
    "features": ["티타늄", "경량", "보온"],
    "usageContexts": ["캠핑장에서 커피나 차를 마실 때"]
  },
  "matchedSignals": [
    {
      "tasteNodeLabel": "캠핑커피",
      "similarity": 0.87,
      "viewType": "usage"
    }
  ]
}

모델 출력의 상품명·특징·취향 표현은 입력 값 안에 존재해야 한다. 후검증에 실패하면 기본 문구로 대체한다. 상품 검색 문서 전체를 프롬프트에 넣지 않는다. 검색 문서에는 모델이 읽을 필요가 없는 중복 표현이 있고, 최종 근거는 구조화된 상품 사실과 matchedSignals로 충분하다.

골드셋의 한 건은 취향 단어 하나가 아니라 프로필 + 추천 모드 + 하드필터 + 관련 상품 집합이다.

{
  "caseId": "gold_001",
  "profile": {
    "hobbies": ["캠핑장에서 핸드드립"],
    "preferences": ["가벼운 장비"],
    "dislikes": ["강한 향"],
    "owned": ["보온 텀블러"]
  },
  "mode": "gift",
  "expectedTasteNodes": ["outdoor.camping.camping_coffee"],
  "relevance": {
    "p_10": 3,
    "p_11": 3,
    "p_21": 2,
    "p_22": 1
  },
  "forbidden": {
    "p_40": "strong_scent",
    "p_41": "already_owned_non_consumable"
  }
}

추천은 정답 하나가 없으므로 단일 expectedProductId를 두지 않는다. 금지 상품은 관련도 0과도 다르다. 유사도가 아무리 높아도 하드필터가 막아야 한다.

초기 골드셋은 확정된 L1 취향 영역을 모두 포함하고, 각 영역에서 다음 유형을 나눈다.

self와 gift, 쉬운 표현과 긴 꼬리 표현, 단일 취향과 복합 취향을 나눠 결과를 본다. 초기 케이스 수는 택소노미와 상품 범위가 정해진 뒤 산정한다. 임의로 전체 개수부터 고정하지 않는다.

현재 검색기가 찾은 결과만 라벨링하지 않는다. 다음 후보를 합친다.

1. direct query의 상위 결과
2. taxonomy 확장 쿼리의 상위 결과
3. LLM rewrite 쿼리의 상위 결과
4. content·usage·gift 각 view의 상위 결과
5. 개발자가 직접 고른 명확한 관련 상품
6. 의미는 비슷하지만 모드가 맞지 않는 hard negative
7. 알레르기·향·보유 조건을 위반하는 금지 상품

이 후보 풀을 개발자가 관련도 0~3과 forbidden으로 라벨링한다. description·query 튜닝에 쓰는 개발 세트와 최종 비교에 쓰는 평가 세트를 분리한다.

한 실험에서는 description 또는 query 중 한쪽만 바꾼다. E4는 앞 실험에서 각각 채택된 변경을 합쳤을 때 상호작용을 보는 마지막 실험이다.

구조적 금지 위반은 품질 평균으로 상쇄하지 않는다. Recall이 올라도 알레르기 위반이 한 건 생기면 그 구성을 채택하지 않는다.

추천 결과가 나빠졌을 때 원인을 구분할 수 있도록 잡 내부에 다음을 남긴다. 대화 원문 전체는 남기지 않는다.

catalogSnapshotVersion
queryStrategyVersion
queryId · sourceSignalKey · viewType
embeddingModelVersion · documentSchemaVersion
topK · similarity
matchedProductIds · filteredCounts
rankerVersion
reasonPromptVersion
latencyMs · retryCount

async def ingest_product(raw: CrawledProduct, space: EmbeddingSpace) -> None:
    product = catalog.normalize(raw)
    semantics = await extractor.extract_product(raw, schema=PRODUCT_SCHEMA)
    filters = validator.verify_filters(raw, semantics.filters)

    documents = document_builder.render(
        product=product,
        semantics=semantics,
        version=space.document_schema_version,
    )
    vectors = await embedder.embed_batch(
        [doc.text for doc in documents],
        model=space.model_name,
    )

    with database.transaction():
        catalog.upsert(product)
        catalog.save_semantics(product.id, semantics)
        catalog.save_filters(product.id, filters)
        catalog.replace_documents(product.id, space.id, documents, vectors)
        catalog.activate_if_searchable(product.id)

async def build_search_queries(profile: TasteProfile) -> list[SearchQuery]:
    seeds = policy.select_query_items(profile, limit=6)

    queries = await rewriter.derive(seeds, schema=SEARCH_QUERY_SCHEMA)

    return [
        policy.restore_server_owned_fields(query, seed)
        for query, seed in zip(queries, seeds)
    ]

restoreServerOwnedFields는 모델 출력의 sourceValue, confidence, hardFilters를 버리고 프로필 원본에서 다시 채운다. 모델이 바꿀 수 있는 것은 검색 문장과 view 후보뿐이다.

async def retrieve_lists(profile: TasteProfile) -> dict[str, RecoList]:
    queries = await build_search_queries(profile)
    vectors = await embedder.embed_batch([q.query_text for q in queries])

    matches = []
    for query, vector in zip(queries, vectors):
        matches.extend(
            catalog.search(
                vector=vector,
                view_type=query.view_type,
                filters=query.hard_filters,
                top_k=80,
            )
        )

    candidates = merge_candidates(matches)

    lists = {}
    for mode in ("self", "gift"):
        ranked = ranking.by_similarity(candidates, mode)
        picked = ranking.diversify(ranked, limit=20)
        reasons = await reasoner.per_query(picked, queries, mode)
        lists[mode] = RecoList(items=picked, reasons=reasons)

    return lists

실제 임베딩 호출은 4단계 결정대로 한 번의 배치 요청이다. 의사코드의 검색 반복은 외부 API 호출이 아니라 PostgreSQL 읽기다. 상품 1만 개 규모에서 쿼리 병렬화가 필요한지는 실행 계획과 처리량을 보고 정한다.

검색 증강을 도입하는 이유는 LLM 입력을 길게 만드는 것이 아니다. 모델이 추천할 수 있는 상품을 실제 카탈로그로 제한하고, 취향과 상품 사이의 근거를 검색 단계에서 만든 뒤, 그 근거만 자연어로 변환하기 위해서다.

니쥬는 텍스트 기반 추천 서비스이므로 report.md가 예시로 든 Visual RAG·Speech RAG·RA-IS는 적용 대상이 아니다. 대신 상품 텍스트와 구조화 속성을 검색해 추천 후보와 생성 근거를 보강하는 구조로 같은 과제 목적을 충족한다.

4단계의 "검색문 재작성 실패 시 잡 실패" 정책은 direct query를 운영 폴백으로 채택할지에 따라 달라질 수 있다. 이 초안에서는 direct를 품질 기준선으로만 확정하고, 운영 폴백 여부는 재작성 실험과 장애 테스트 후 결정한다. 결정되기 전까지 기존 실패 계약을 유지한다.