> For the complete documentation index, see [llms.txt](https://genos-docs.gitbook.io/default/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://genos-docs.gitbook.io/default/v1.9.4/basic-tutorials/guides/data/faq-metadata.md).

# FAQ 메타데이터

FAQ 메타데이터는 FAQ 항목에 **카테고리·갱신일·우선순위·채널처럼 원하는 부가 정보를 자유롭게 붙여 두는 기능**입니다. 지금까지 FAQ 벡터DB에는 질문·답변과 등록일 외에 붙일 수 있는 정보가 없어서, 워크플로우가 검색된 FAQ 중 무엇을 쓸지 고를 근거가 유사도뿐이었습니다. 메타데이터를 넣어 두면 검색 결과에 함께 실려 나가므로, 워크플로우에서 "오래된 FAQ는 쓰지 않는다", "B2C 채널 FAQ만 쓴다" 같은 **후처리 필터·정렬·로깅**에 쓸 수 있습니다.

입력 위치는 **관리자 > 데이터 > 벡터DB > (FAQ 타입 벡터DB 선택) > FAQ 목록**입니다. FAQ를 등록할 때 함께 입력하거나, 이미 등록된 FAQ를 선택해 나중에 채워 넣을 수 있습니다.

<figure><img src="https://1274363562-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJuB29xjw7zmR91VXmqf%2Fuploads%2Fgit-blob-07e1d0e5bbcc79e14c156fb0770a5574c1d19cf0%2Ffaqmeta_01_faq_list_metadata_column.png?alt=media" alt=""><figcaption><p>FAQ 목록의 메타데이터 컬럼</p></figcaption></figure>

> **적용 대상은 FAQ 타입 벡터DB입니다.** QA 타입 벡터DB에는 메타데이터 입력·수정 화면이 제공되지 않습니다.

### 주요 개념

| 개념        | 설명                                                                                                              |
| --------- | --------------------------------------------------------------------------------------------------------------- |
| 메타데이터     | FAQ 한 건에 붙이는 JSON 객체 형태의 부가 정보입니다. 키 이름과 값은 사용자가 자유롭게 정합니다.                                                     |
| 후처리 필터    | 워크플로우가 FAQ를 검색한 **뒤에** 메타데이터를 보고 후보를 걸러내거나 순서를 바꾸는 단계입니다.                                                       |
| fail-open | 메타데이터가 없는 FAQ는 필터에서 탈락시키지 않고 그대로 통과시키는 정책입니다. 기존에 등록된 FAQ가 갑자기 검색에서 사라지지 않도록 하기 위함입니다.                          |
| 메타데이터 속성  | 벡터DB 안에서 메타데이터를 담는 자리입니다. FAQ 벡터DB를 새로 만들면 처음부터 생기고, 기존 벡터DB는 메타데이터를 처음 저장하는 시점에 자동으로 추가됩니다. 별도 준비 작업은 필요 없습니다. |

### 메타데이터 작성 규칙

어느 입력 경로에서든 같은 규칙이 적용됩니다.

| 규칙    | 내용                                                                                                         |
| ----- | ---------------------------------------------------------------------------------------------------------- |
| 형식    | **JSON 객체**만 허용됩니다. `{"category": "주문배송", "priority": 5}` 형태로 작성하며, 배열(`[...]`)이나 문자열·숫자 단독 값은 저장할 수 없습니다. |
| 선택 입력 | 비워 두어도 됩니다. 빈 값과 `{}`(빈 객체)는 모두 "메타데이터 없음"으로 저장됩니다.                                                        |
| 키 이름  | 비어 있는 키는 사용할 수 없습니다. 키 이름 자체는 자유이며, 워크플로우 필터에서 쓰는 이름과 맞추면 됩니다.                                             |
| 크기    | 전체 16KB(16,384바이트)까지입니다. 본문이 아니라 필터용 키-값을 담는 자리입니다.                                                        |
| 검색    | 메타데이터 **내용으로 검색·정렬할 수는 없습니다.** 목록 검색 필드는 서빙·ID·질문·답변·사용자 ID이며, 메타데이터는 조회·표시·워크플로우 전달용입니다.                  |

권장 키 예시 — 워크플로우 후처리에서 실제로 많이 쓰는 형태입니다.

```json
{ "category": "주문배송", "updated_at": "2026-03-11", "priority": 5, "channel": "B2C" }
```

### FAQ 한 건 등록하면서 입력하기

FAQ 목록 화면 우측 상단의 **업로드** 버튼을 누르면 **FAQ 추가** 다이얼로그가 열립니다. 유형을 **단 건 추가**로 두면, 질문·답변 아래에 **메타데이터** 입력란(JSON 편집기)이 나타납니다. 안내 문구는 "선택 입력. JSON 객체 형식으로 작성하면 워크플로우 후처리 필터에 사용할 수 있습니다."입니다.

<figure><img src="https://1274363562-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJuB29xjw7zmR91VXmqf%2Fuploads%2Fgit-blob-4bbe67798a2d89f94dbfcd9d3f51ee869f9ac115%2Ffaqmeta_02_add_faq_single_metadata.png?alt=media" alt=""><figcaption><p>FAQ 추가 다이얼로그 — 단 건 추가의 메타데이터 입력란</p></figcaption></figure>

* 입력란은 **단 건 추가** 유형에서만 보입니다. **csv 파일로 여러 건 추가** 유형에서는 메타데이터를 파일의 3번째 컬럼으로 넣습니다.
* 작성 중 형식이 잘못되면 입력란 아래에 오류가 표시되고 저장이 막힙니다. 저장 전에 고쳐야 합니다.
* 비워 둔 채 저장하면 메타데이터 없는 FAQ로 등록되며, 나중에 [메타데이터 수정](#메타데이터-수정하기-여러-건-한꺼번에)으로 채울 수 있습니다.

### CSV로 여러 건 등록하기

FAQ 추가 다이얼로그에서 유형을 **csv 파일로 여러 건 추가**로 선택하면 **2컬럼과 3컬럼을 모두 받습니다.** 화면 안내 문구도 같습니다 — "CSV는 \[질문, 답변] 2컬럼 또는 \[질문, 답변, 메타데이터] 3컬럼을 지원합니다. 메타데이터 컬럼은 JSON 객체 문자열로 작성하세요."

<figure><img src="https://1274363562-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJuB29xjw7zmR91VXmqf%2Fuploads%2Fgit-blob-6ac668c481e53a68abd503279247a9f7bfdc43c6%2Ffaqmeta_03_add_faq_csv_metadata_help.png?alt=media" alt=""><figcaption><p>FAQ 추가 다이얼로그 — csv 파일로 여러 건 추가와 메타데이터 안내 문구</p></figcaption></figure>

| 컬럼 수                             | 동작                                                                 |
| -------------------------------- | ------------------------------------------------------------------ |
| 2컬럼 (`question,answer`)          | 기존에 쓰던 파일 그대로 동작합니다. 메타데이터 없이 등록됩니다.                               |
| 3컬럼 (`question,answer,metadata`) | 3번째 컬럼의 JSON이 그 행의 메타데이터로 저장됩니다. **셀을 비워 두면** 그 행만 메타데이터 없이 등록됩니다. |

```csv
question,answer,metadata
"주문을 취소하고 싶어요","마이페이지 > 주문관리에서 취소할 수 있습니다.","{""category"":""주문배송"",""updated_at"":""2026-03-11"",""priority"":5}"
"배송은 얼마나 걸리나요","평균 2~3일 소요됩니다.",
```

> CSV 안에서 JSON을 쓸 때는 큰따옴표를 **두 번씩**(`""`) 적어야 합니다. 위 예시의 `""category""` 가 그 형태입니다. 엑셀에서 셀에 `{"category":"주문배송"}` 을 그대로 입력하고 CSV로 저장하면 자동으로 이 형태가 됩니다.

**잘못된 행이 하나라도 있으면 전체가 등록되지 않습니다.** 형식 오류가 있는 행 번호와 이유가 담긴 오류 메시지가 표시되므로, 해당 행을 고쳐 다시 올리면 됩니다. 일부만 들어가 중복 정리를 해야 하는 상황이 생기지 않도록 한 설계입니다.

### 목록에서 메타데이터 확인하기

FAQ 목록에 **메타데이터** 컬럼이 있습니다.

* 값이 있으면 JSON을 한 줄로 줄여 보여 주고, 칸을 넘치면 말줄임으로 표시합니다. **마우스를 올리면 전체 JSON이 줄바꿈·들여쓰기된 형태로** 펼쳐집니다.
* 값이 없으면 `-` 로 표시됩니다.
* 이 컬럼으로는 정렬할 수 없습니다.

<figure><img src="https://1274363562-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJuB29xjw7zmR91VXmqf%2Fuploads%2Fgit-blob-7530d9ee0a1319a99cebb596b99436472cf732a4%2Ffaqmeta_04_metadata_tooltip.png?alt=media" alt=""><figcaption><p>메타데이터 셀에 마우스를 올리면 전체 JSON이 펼쳐진다</p></figcaption></figure>

### 메타데이터 수정하기 (여러 건 한꺼번에)

목록에서 **체크박스로 FAQ를 선택**한 뒤 상단의 **메타데이터 수정** 버튼을 누릅니다.

| 상황                   | 화면 동작                                                                               |
| -------------------- | ----------------------------------------------------------------------------------- |
| 수정 권한이 없는 사용자        | 버튼이 보이지 않습니다.                                                                       |
| 선택한 행이 0건            | 버튼이 비활성 상태입니다.                                                                      |
| 선택한 행들의 메타데이터가 모두 같음 | 그 값이 편집기에 채워진 상태로 열립니다.                                                             |
| 선택한 행들의 메타데이터가 서로 다름 | 편집기는 **비어 있고** "선택한 FAQ의 메타데이터가 서로 다릅니다. 저장하면 선택한 항목 전체가 아래 값으로 덮어써집니다." 경고가 표시됩니다. |

<figure><img src="https://1274363562-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoJuB29xjw7zmR91VXmqf%2Fuploads%2Fgit-blob-70f297a022b60a9144cddbf68f94febe4c293b11%2Ffaqmeta_05_edit_metadata_dialog.png?alt=media" alt=""><figcaption><p>메타데이터 수정 다이얼로그 — 선택 건수 안내와 값이 서로 다를 때의 경고</p></figcaption></figure>

다이얼로그 상단에는 "선택한 FAQ N건의 메타데이터를 같은 값으로 변경합니다."가 표시됩니다. 선택한 **모든 항목이 입력한 값으로 동일하게 덮어써집니다** — 항목마다 다른 값을 넣으려면 나누어 수정해야 합니다.

* **삭제**: 편집기를 비우고 저장하면 메타데이터가 삭제됩니다("비워 두고 저장하면 메타데이터가 삭제됩니다." 안내).
* 저장 버튼을 누르면 확인 창이 한 번 더 뜨고, 성공하면 완료 토스트가 표시되며 목록이 갱신됩니다.
* **질문·답변은 전혀 변경되지 않고 재임베딩도 일어나지 않습니다.** 벡터는 질문만으로 만들어지고 메타데이터는 부가 정보만 갱신하기 때문에, 수정 후에도 검색 품질과 검색 순위는 그대로입니다. 대량 수정도 임베딩 비용 없이 즉시 반영됩니다.

이미 등록되어 있던 FAQ(메타데이터 없이 적재된 기존 데이터)는 일괄 채워 넣는 작업이 자동으로 수행되지 않습니다. 필요한 항목만 이 화면에서 선택해 채워 넣으면 되며, 채우지 않은 FAQ는 워크플로우 필터에서 fail-open(통과)으로 처리됩니다.

### 워크플로우에서 메타데이터 활용하기

메타데이터는 저장만 해 두면 자동으로 쓰이는 값이 아니라, **워크플로우에서 받아서 쓰도록 설정해야** 동작합니다. FAQ 벡터DB를 Knowledge로 연결한 에이전트 기준으로 세 곳을 설정합니다.

**① Knowledge(Vector Embeddings) 노드**

| 필드                     | 설정값                                                               |
| ---------------------- | ----------------------------------------------------------------- |
| Weaviate Index         | 사용할 FAQ 벡터DB 인덱스                                                  |
| Weaviate Text Key      | `text` (FAQ 벡터DB 생성 시 지정한 답변 키)                                   |
| Weaviate Metadata Keys | 기존 값에 **`metadata` 를 추가** (예: `["ref_text", "text", "metadata"]`) |
| Top K                  | **5\~10** 권장                                                      |

> `metadata` 를 Metadata Keys에 넣지 않으면 값이 검색 결과에 실려 오지 않아 필터가 아무 일도 하지 않습니다. 또한 **Top K가 1이면** 1순위 한 건만 보게 되어, 필터가 "후보 중 고르기"가 아니라 "그 한 건 탈락"으로 동작합니다.

**② 에이전트 프롬프트** — 검색 결과를 여러 건의 배열로 받고 각 건에 `metadata` 를 포함해 출력하도록 작성합니다. 이때 메타데이터 자리표시자는 **중괄호(객체)** 로 써야 합니다. 대괄호로 쓰면 모델이 배열로 출력해 필터가 값을 읽지 못합니다.

**③ Custom Function(후처리) 노드** — 전달받은 결과에서 메타데이터를 읽어 걸러냅니다. 갱신일 기준 신선도 필터, 채널·카테고리 필터, 동점 시 우선순위 정렬이 대표적입니다. 모든 후보가 걸러지면 일반 RAG 경로로 넘기는 분기를 함께 두고, 메타데이터가 없는 FAQ는 통과(fail-open)로 처리합니다.

> **알려진 한계 — 유사도 점수** Knowledge 검색의 실제 유사도 점수는 에이전트에게 전달되지 않습니다. 프롬프트로 받은 `similarity_score` 는 모델이 생성한 값이므로 임계값 비교의 근거로 삼기에는 부정확합니다. 점수를 신뢰해야 하는 필터가 필요하면 Retriever 노드를 별도로 두고 점수를 직접 전달해야 합니다.

### 오류·예외 처리

| 발생 상황                                           | 화면 문구                                  |
| ----------------------------------------------- | -------------------------------------- |
| 벡터DB에 메타데이터 속성을 추가하지 못함                         | metadata 속성 추가에 실패했습니다. (사유)           |
| CSV 특정 행의 메타데이터 형식 오류(JSON·크기·빈 키) → **전건 미적재** | CSV {행}행의 metadata 형식이 올바르지 않습니다. (사유) |
| 수정 대상 FAQ가 없거나 이미 삭제됨                           | 수정 대상 FAQ를 찾을 수 없습니다. \[ID]            |
| 벡터DB 반영 실패                                      | 벡터DB 반영에 실패했습니다. (사유) 되돌리지 못한 항목: ID   |

입력 형식 오류(JSON이 아님, 객체가 아님, 16KB 초과, 빈 키)는 저장 전에 입력란에서 차단됩니다.

> **일괄 수정이 중간에 실패한 경우** — 벡터DB에는 트랜잭션이 없어 여러 건을 한 번에 되돌릴 수 없습니다. 그래서 중간 실패 시 이미 반영된 건을 원래 값으로 되돌리려 시도하고, 되돌리지 못한 항목의 ID를 "벡터DB 반영에 실패했습니다." 메시지에 담아 알려 줍니다. **같은 값으로 다시 저장하면 상태가 정상으로 수렴**하므로, 메시지에 항목이 남아 있으면 그 항목을 다시 선택해 저장하세요.

### 사용자 시나리오

**① 오래된 FAQ가 답변으로 나가지 않게 하고 싶다**

FAQ마다 `updated_at` 을 메타데이터에 넣습니다 → Knowledge 노드의 Metadata Keys에 `metadata` 를 추가하고 Top K를 8로 올립니다 → 후처리 함수에 갱신일 기준 필터를 둡니다. 결과적으로 질문과 더 비슷하지만 오래된 FAQ는 탈락하고, 조금 덜 비슷하지만 최신인 FAQ가 답변으로 선택됩니다.

**② 채널별로 다른 FAQ를 쓰고 싶다**

`channel` 키(`B2C`/`B2B`)를 넣고 후처리 함수에서 현재 사용자 채널과 비교해 걸러냅니다. 채널 정보가 없는 FAQ는 통과되므로, 채널 구분이 필요한 FAQ에만 키를 넣으면 됩니다.

**③ 이미 수백 건 등록된 FAQ에 정보를 채워야 한다**

목록에서 같은 카테고리 FAQ를 체크박스로 선택 → **메타데이터 수정** → `{"category":"주문배송"}` 저장. 카테고리 단위로 반복합니다. 재임베딩이 없어 대량으로 해도 시간과 비용이 들지 않습니다. 채우지 않은 FAQ는 필터에서 통과 처리되므로 한 번에 다 채우지 않아도 검색이 깨지지 않습니다.

**④ 기존 2컬럼 CSV를 계속 쓰고 있다**

그대로 쓰면 됩니다. 나중에 메타데이터 컬럼만 추가하면 되고, 일부 행만 채워도 됩니다.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://genos-docs.gitbook.io/default/v1.9.4/basic-tutorials/guides/data/faq-metadata.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.