10분 만에 만드는 캠핑 용품 검색

캠핑 용품 2,000개를 로컬 UQA에 저장하고 검색 화면까지 실행합니다. 임베딩 모델 약 600MB를 처음 내려받는 과정도 포함해요.

UQA와 UQA 사용법 스킬을 설치합니다. 이미 설치했다면 버전 확인만 실행하면 돼요.

curl -fsSL https://releases.uqa-cloud.cognica.io/install.sh | sh
uqa llm install skills --agent all --scope user --output json
uqa --version

--version은 설치한 버전을 물어보는 옵션입니다. 터미널은 uqa 0.1.52처럼 프로그램 이름과 버전 숫자를 표시해요. 버전 숫자는 설치한 시점에 따라 달라집니다. command not found: uqa가 나오면 설치할 때 안내한 실행 경로가 아직 이 터미널에 적용되지 않은 상태예요. 터미널을 새로 실행하고 같은 명령을 다시 실행하면 됩니다.

shop-search라는 로컬 프로젝트를 생성합니다. 로컬 프로젝트는 이 컴퓨터에서만 연결되며 계정 등록이나 별도 서버가 필요하지 않아요.

uqa local db create shop-search --output json
uqa local db status shop-search --output json
uqa local db doctor shop-search --output json

상태 출력에서 state가 ready, health가 healthy면 다음 단계로 넘어갑니다. 둘 중 하나라도 다르면 프로젝트가 아직 실행되지 않은 상태예요. 클로드나 코덱스에게 프로젝트를 다시 실행해 달라고 요청하고, state와 health가 각각 ready와 healthy로 바뀌는지 확인하세요.

3단계에서 준비하는 실행 파일(camping-search.mjs)은 UQA CLI에서 연결 주소와 토큰을 메모리로만 읽습니다. 접속 토큰을 소스 코드, 브라우저 저장소, .env 파일에 기록하지 않습니다.

실습에 사용하는 실행 파일은 camping-search.mjs 하나입니다. Node.js로 실행하는 스크립트 파일이고, 이 파일로 실습 데이터 다운로드부터 검증, 데이터 분할 적재, 검색, 검색 화면 실행까지 전 과정을 처리합니다. 캠핑 용품 2,000개의 임베딩이 미리 포함되어 있어, 상품 설명을 임베딩으로 변환하는 과정을 건너뜁니다.

임베딩은 상품 설명을 의미 검색이 비교할 수 있는 숫자 목록으로 바꿔 둔 데이터입니다. 상품 2,000개를 직접 변환하려면 모델이 설명을 2,000번 읽어야 해서 시간이 오래 걸려요. 이 실습에서 확인할 것은 변환 과정이 아니라 검색 결과라서, 상품 임베딩은 미리 변환해 제공합니다. 다만 검색어는 입력할 때마다 새로 변환해야 하므로 모델 다운로드는 그대로 필요합니다.

클로드나 코덱스가 실습 폴더, 실행 파일, 임베딩 패키지를 준비합니다. 모델 다운로드와 1,024차원 확인까지 한 요청으로 진행해요.

mkdir camping-search
cd camping-search
npm init -y
npm install @huggingface/transformers@3.8.1
curl -fsSLO https://uqa-landing.vercel.app/tutorials/camping-search/camping-search.mjs
node camping-search.mjs model

• Xenova/bge-m3 q8 약 600MB 최초 다운로드

• CLS pooling과 정규화 적용

• 검색어 임베딩 1,024차원 확인

마지막에 모델 준비 완료: 1024차원이 출력되면 준비가 끝납니다. 모델 파일은 ~/.cache/transformersjs에 저장되며 다음 실행부터 재사용해요. 다운로드가 중단됐다면 같은 명령을 다시 실행하면 됩니다.

적재 명령은 CSV, 상품 임베딩, 메타데이터를 내려받고 파일 해시를 검증합니다. CSV의 BOM과 따옴표를 처리한 뒤 상품을 12개씩 전송하므로 한 요청의 크기가 커져 실패하는 일을 방지해요.

node camping-search.mjs load

실행 파일은 같은 ID의 상품을 갱신하는 방식으로 적재합니다. 명령을 다시 실행해도 상품 2,000개가 중복으로 증가하지 않아요.

CREATE TABLE IF NOT EXISTS camping_products (
  id          INTEGER PRIMARY KEY,
  name        TEXT NOT NULL,
  description TEXT NOT NULL,
  search_text TEXT NOT NULL,
  embedding   VECTOR(1024) NOT NULL
);

CREATE INDEX IF NOT EXISTS camping_products_search_gin
ON camping_products USING gin (search_text)
WITH (analyzer = 'standard_cjk');

CREATE INDEX IF NOT EXISTS camping_products_embedding_hnsw
ON camping_products USING hnsw (embedding);

진행 숫자가 상품 적재 2000/2000에 도달하고 적재 완료: 2000개가 출력돼야 합니다. 실행 파일은 적재 직후 UQA에서 상품 수를 다시 조회해 CSV 행 수와 비교해요.

단어 검색은 검색어와 글자가 겹치는 상품에 점수를 계산합니다. 의미 검색은 검색어 임베딩과 상품 임베딩의 거리를 비교해 표현이 다른 상품도 찾아요. UQA는 이 두 점수를 SQL 한 문장에서 함께 구하고, 하나로 합친 점수가 높은 상품부터 보여줍니다. 이 실습의 검색에서는 합친 점수가 0에서 1 사이로 나옵니다. 화면에는 그 점수를 그대로 표시하세요. 백분율로 바꾸면 검색 방법에 따라 100%가 넘는 숫자가 나올 수 있어요.

node camping-search.mjs search "겨울에도 따뜻한 침낭"
node camping-search.mjs search "추운 텐트에서 자는 동안 체온을 지켜주는 장비"

현재 실습 데이터에서는 동계용 사각 침낭이 첫 결과로 조회되고, 상위 다섯 상품의 점수는 0.44에서 0.08까지 내려갑니다. 상품 데이터나 임베딩 모델을 변경하면 순위와 점수도 달라질 수 있어요.

SELECT id, name, description, _score
FROM camping_products
WHERE text_match(search_text, $1)
  AND knn_match(embedding, $2, 100)
ORDER BY _score DESC, id ASC
LIMIT 5;

첫 검색에서는 동계용 사각 침낭이 먼저 표시되고, 상품명에 침낭이 없는 두 번째 검색에서도 상위 다섯 상품이 모두 침낭류로 조회됩니다. 검색어별 결과가 확인되면 상품 적재, 질의 임베딩, 단어 검색 색인, 의미 검색 색인이 연결된 상태입니다. 검색어 임베딩 생성에 실패하면 실행 파일은 오류 코드를 표시해요.

제공한 실행 파일에는 검색창과 결과 목록이 포함돼 있습니다. 로컬 웹 서버는 127.0.0.1에서만 연결을 허용하고, UQA 접속 토큰과 임베딩 모델은 서버 프로세스 안에서 관리해요. 포트는 기본 4173을 사용하고, 이미 사용 중이면 빈 포트를 찾아 실행한 주소를 알려줍니다.

node camping-search.mjs serve

클로드나 코덱스가 검색 화면 주소를 알려주면 브라우저에서 상품명, 설명, 검색 점수 다섯 개를 확인합니다.

다음 네 항목을 확인하면 10분 실습 구간이 끝납니다.

1. 1

   camping_products에 상품 2,000개 저장

2. 2

   겨울에도 따뜻한 침낭 검색에서 동계용 침낭 우선 표시

3. 3

   상품명과 표현이 다른 질의에서도 침낭류 다섯 개 표시

4. 4

   UQA 재시작 후 같은 검색 결과 반환

uqa local db restart shop-search --output json
node camping-search.mjs search "겨울에도 따뜻한 침낭"

UQA를 재시작한 뒤에도 같은 상품을 검색할 수 있으면 데이터와 색인이 로컬 프로젝트에 유지된 것입니다.

실제 상품 CSV를 적용할 때는 상품 ID, 상품명, 설명을 먼저 정리합니다. 상품 설명과 검색어에 같은 임베딩 모델, pooling, 정규화, 1,024차원 설정을 적용해야 해요.

실제 상품의 임베딩 생성 시간은 상품 수와 컴퓨터 성능에 따라 달라집니다. 먼저 상품 20개로 적재와 검색을 확인한 뒤 같은 코드를 전체 파일에 적용해요.

UQA 질의 오류에는 오류 코드와 요청 ID가 표시됩니다. 오류 코드와 요청 ID를 클로드나 코덱스에 전달하면 로컬 프로젝트 상태와 최근 로그를 함께 확인할 수 있어요.