요구사항 → 데이터 자산 스마트 매칭 시스템

FastAPI · BM25 · 벡터 하이브리디 검색 · 교차 인코더 정렬 정렬 · 보정 가능한 판정기능을 가진 이이전트 폐루프 · MCP

시스템은 자연어 요구, 요구 스크린샷 또는 임 의 레이아웃의 Ecel을 입려받아, 데이터 자산 카다거리에서 시용 가한 테이블을 마치해 필드 단위 근거가 들은 추천 방을 출합니다.

마치 공은 단방향 호이 아니라 이전트 폐루프입니다. 각 마치 결과가 나올과 판정합기는 후보 자산과 요구의 재한성을 것을 별로 평성합니다(된/부분 관련/무 관련). 기일에 미치지 못하면, 시스탬은 마치 중간 상터에서 얻은 인단 결론에 다라 스스로 선택정 동작을 선택해 디시 검색합니다. 거리에 실니하게 지지할 만한 여자산이 없으면 시원 불가 판정에 근거를 출력하며, 자슷한 결과로 지ㅂ지 않습니다. 사용자가 반환된 결과에 수정 의군을 제시하면, 시스탬은 이전 판정의 잝텍스트를 유지한 상대로 계속해서 안전을 이어합니다.

이이전트 폐루프

자모 검

각 검색 라운드 후, 판정합이 각 후보와 요구와의 재합한(연한/ 연관/ 무관련)을 판조하고, 코리라 이을 집합하여 은수로 반환해 임계값과 비교합니다. 임계값에 미치하면 교정 단체로 범들합니다.

match（检索）→ judge（逐条判相关性）→ 达标？
                                      ├ 是 → 交付
                                      └ 否 → 选纠偏动作 → 重新检索 → 再判

자율 교정: 검색 전략은 조절 가능하며 판정 기준은 조절 불가

교정 동오은 고정된 목록에서 가져며, 권한 경골는 코가 강자하지 않으며, 프록프트 지율에 의존하지 않습니다:

판정 한도를 조절하면 사용 결과를 성립시키기 위해 모모델의 인정 기준을 낮추는 것과 같으므로 "지원 불가" 판정이 무효가 될 수 있으며, 조절 가능한 허용 목록에 포함되지 않고 텈스트로 제한합니다.

근거가 있는 원인 규명

교정 전에 코더는 검색 중간 상태에서 근거 있는 진단 결과를 계산해 판정기에 제출합니다. 같은 현상은 일반적으로 두 가지 원인에 해당하며 처리방향이 반계이기 때문에, 진단의 역할은 다음 둘을 별하는 것입니다:

• 후보 풀이 너무 작음 -> 원인 유지 부족 → 인자 조정 | 원인 필터 과잉 → 이완 조계

• 범자가 지나무 낮은 연 -- 원인 필드 추출 오유 → 추출 결과 수정 | 원인 디렉터리에 실니 지 — 지원 불가 판정

다중 차례 협력

• 본해 후 확인: 추출 결과는 사용자가 사전에 확인하고 추가/삭ण한 후 검색에 들어가게 됩니다 — 오류 수정 비용이 가장 낮은 과정주를 최상단에 놓습니다.

• 결강 후 질의: 사용자가 수정 의견을 제시하면, 이전 대하 기록을 유지한 채 계속 교정를 계속하며, 컨텐스트를 초기화하지 않습니다.

• 대횽 화면화: 대화 상태가 디스크에 저장되어, 서비스 재시정 후 session_id가 계속 유효합니다.

감사 가능, 중단 가능

모든 단계에서 action / reason / verdict / effect(실행 동작, 의전 근거, 판정 원문, 전후 차이)를 기록하고 결과와 함께 반환합니다. 첫 번거 동작은 항시 전체 검색이므로, 어떤 시간적인 반에도 전달 가능한 결과가 있으며, 최악지 경우 동일한 초기 검색와 같습니다. 길고한 작업은 협조하여 취소할 수 있습니다.

판정자를 신 개조정

판정자가 자동적 의사결정 체인 전단계에 진입하려면, 인공 금표 (label)로 신체정 판정 요과와 진실한 우열 차이를 측해야 합니다(Cohen's κ), κ > 0.6일 경우에만 자동 결정 공정에 사용하며 모델을 곁한하거나, 프롬프트를 수정하거나, 집환 규칙을 수정한 경할 다시 개정해야 합니다.

Related MCP server: MCP RAG Agent Server

자동 우선 순인 추천

관직성과 자산 우선 순인(이미 주찬되었는지, 자산 유형, 데 이터 웨어하우스 계층)는 단추이 다르기 때문에, 직접 가중치는 인력 비합산(parameter weight)와 시간적 결과을 것을 되습니다. 시스템은 자율 경계 기반 그룸화 + 그룸 내 문자 순 순서를 사용합니다:

1. 최소 인식 가능 개̂ (JND) 추정: 이 요청의 후보 관련성 점수를 내림차순으로 정렬한 한 점수 차이의 중앤값(median)을 기점으로, "이 질의에 대한 일반적인 점수 차이가 얼마인가" 하는 것을 답할합니다.

2. 자연 경계 조 그룲: 현재 최 고정부터 아래로 확장하여, 간격 > gap_factor × ρ인 유위한 조를 만날 때만분. 점수가 근접한 경우 (거인 동거으록)은 조금으록 하지 않으인, 우선 순위로 순서를 결하합니다. 뚜렷한 조를 갖는 경우에는 관련성이 우위합니다.

3. 그룸 내 고정 순서: 【우선 순위 최최선 → 관련성 → 최대 범위 → 더 적은 스키마 수】의 사전순으로 최종 순서를 결。정합니다. 통합 시안의 순위는 중 한원의 최저 순위를 사용하므로, 하 높은 순위 한 개가 낮은 순위를 다 조 여러분 끌어 및위도 하지 않습니다.

그룸의 속는 데이터에 따라 자율적으로 조응하며, 질의 형태에 따라 미리 정의되지 않은 분기 gor지 않습니다 — "사용자가 무근 것을 부는가"를 사전에 하드코드 로직에 사용하는 것은 수동 가중고 같은 류의 문계입니다.

우선 순위 가지는 "해당 자산이 구매되었는지 + 자산 유형 + 데이터 웨어 하우스 계층"의 사전순으로 경합되며, 매핑는 모드 구성 파일에서 얻습니다:

# config/config.yaml → matching.ranking.priority
ordered_rank: 6         # 已订购（由订购清单 vlookup 标记，最高档）
asset_type_rank: {...}  # 资产类型 → 档位
layer_only_types: [...] # 仅这些类型内部再按数仓层级细分
layer_rank: {DWA: 5, DIM: 5, DWV: 4, DWI: 3, ODS: 2, STG: 1}

# config/config.yaml → matching.layering
gap_factor: 2.0         # 间隙达 JND 几倍算断层：越大同档越宽，越偏向优先级
min_jnd: 0.02           # JND 绝对下限，仅兜底分数全等 / 单点等退化情形

기타 기기

• 산의 레이아웃 분해: 텍스트 / 스크린샷(시각 사전을 이용한 전환) / E에xl(산의 레이아웃) 모드 입자가 통일됩니다; 영역은 필터 단계의 다섯 가지 저급 방식으로를 제공하며, 앞 수 없은 레이아웃도 항상 출력을 보합니다.

• 혼합 색색: 특정 (BM25) + 밀은 의미 벡터 + 필드 역방 목록의 세 경로 로콜 → RRF 결합 → 교차 인코더 빌충 정렬; 반조적인 인코딩와 상위 2개 풀로 알고리즘으로 표 이름 의미가 다수 필드로 들하지 않도록 합니다.

• 조함 시안: 하나의 표만으로 덮지 못하면 연결 키를 공유하는 다수의 표를 조함할 수 있습니다.

• 3가지 접겸: 웹 인터패이스 / REST API / MCP (의개 도구 + 비동기 작업 + 협동 취소).

• 자동 저급: GPU가 없거나 모델 고비가 없으면 사용 가능한 리소스를 사용하여 자동으로 등급이 낮아지며, 품질은 저하되지만 연동이 중단되지 않습니다; 저급 항목은 /api/health에서 보고되고 모니터링을 연결할 수 있습니다.

빠른 시작

python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# 可选：安装后启用语义召回 / 精排 / 本地大模型；未安装则自动降级为词法检索 + 规则解析
pip install sentence-transformers
pip install torch --index-url https://download.pytorch.org/whl/cpu

python -m uvicorn src.api.app:app --host 127.0.0.1 --port 8001

웹 인터패이스는 http://127.0.0.1:8001에 있습니다. API 호출:

# 一步式：解析 → 检索 → 自我审阅 → 交付
curl -X POST http://127.0.0.1:8001/api/agent/run \
  -F "text=分析会员复购行为，需要用户ID、订单数、支付金额"

# 多轮：对上一轮结果提出修正意见，携带历史继续纠偏
curl -X POST http://127.0.0.1:8001/api/agent/resume \
  -F "session_id=<上一轮返回的 session_id>" \
  -F "feedback=当前结果不符合预期，需要履约时效相关的资产"

예시 카탈로그는 리포지토리와 함께 제공됩니다(data/samples/, 3000개의 표, 거래, 사용자, 제품, 이행, 마케팅, 서비스, 리스크, 컨텐츠, 위치, 재무 등 10개 비즈니스 도메인 포함), 별도 준비가 필요하지 않습니다; CPU 환경에서도 실행할 수 있습니다.

첫 번째 요청은 검색 인덱스를 구축하고 모델을 로드하는 데 몇 분간 시간이 걸립니다. (CPU에서 3000개의 테이블) 인덱스는 data/.cache/ 경로에 저장되며, 그 후에는 콘텐츠 지홍 기준으로 캐시 지문을 사용하기 때문에 재시작 시 재구현되지 않습니다.

자체 데이터로 전환

시스템은 추출 대상물의 유형, 기존 자사 요구에 제한적으로 고정하지 않습니다: 데이터 항목을 "항목 + 속성 목록 + 설명"의 구조로 정리할 수 있는 형식이면 바로 사용할 수 있습니다. 데이터테이블, 문서 라이브러리, 상품, API, 정보 항목 모두 적용 가능하며, 검색, 정렬, 에이전트 로직을 변경할 필요가 없습니다.

1. 꼭 수정해야: 카탈로그 데이터

다음과 같은 구조의 CSV 파일을 쓸 준비합니다(예시는 data/samples/assets.sample.csv):

# config/config.yaml
data:
  assets_file: data/自有目录.csv      # 默认按 gb18030 读取

기본 인고드은 gb18030입니다. 카타로그 파일이 UT-F-8이면, 사전에 인고드를 변환하든지, src/data_loader.py의 인고드 코드(해당 곳만 코딩 인고드와 연관된 유일한 변경 지점)를 수정하십시오.

열거 값은 정렬 로직과 일치해야 합니다. 자식 유형 / 레벨 / 주기라는 세 열은 가중치 없이 우선순위 및 물리 필터에 참여하므로, 해당하는 맵일 (map)테이블에 있어야 합니다. 없는 경우 해당 행은 최저 레벨로 거락되고 영원히 매칭될 수 없습니다:

카탈로그를 바후, 자체 값인 여러 매핑 표목록에 추가하거나 데이터를 기존 값으로 적용할 수 있습니다. 데이터 도메인은 단일 위수(같은 레벨의 열기값)을 유지해야 합니다;놉출이 같지 읂은 또는더 그룹 인더모 이 도메인 필터으로 인출 과목등이 새비트지 않습니다. 예시 카타로그는 이 기준을 지.

ordered_rank(이미 상품 구)는 data.ordered_file이 참고하는 주문서 목록에 의존합니다. 예시 기본설정에는 파일이 포함되지 않지 때문에 이 순위는 활성화되지 않으나, 자체 목록을 연결하면 자동으로 동적합이로 활법합니다.

2. 권장: 네 개의 도메인 단어 파일(직거은 재호)

동의어 파일은 data.synonym_file의 경기를 통해 바 있습니다. 나머지 세 번은 pipeline.py 및 nomalize.py에 신하에코드 수정 없이 파일 내용을 교체할 수 있습니다. 이제 냄겨 있는 네 개의 하는 세트는 초기를 위한 규모로, 동의어 8 set, 분류 64, 고유 명사 67개 정도이고, 자체 도메인에 마추어 추가할 수 있습니다.

그 중 동의어 다음이 가장 치이 높습니다. 형식은 {"규범 단어": ["별명1", "별명2"]}으로, 카탈로그 필드 이름에 삶은 의 개념에 여러 따랰음을 하나로 묶으면 됩니다. 약 10개이 그룹을 포하ㅣ면 효과 있.

3. 교환 가능: 추출 프롬트의 예시 교체

src/matching/extractor.py와 src/matching/llm_p.py의 프롬트는 데메인 예시를 포함하고, "어떻게 해야 하나요"과 "필이"를 정의하는 용으로 사용됩니다. 이 예시가 논리 분기를 대표하지는 않지만, 자체 도메인의 개가 두 개의 예시로 교체하면 해석 품이. 분명히 조습니다.

4. 교체 후 반드시 재명시

• 의미황 임계값: field_match.retrieve_min_sim와 min_se는 모델이라 모형, 값, 임의 모형 및 도메인의 가서 분포에 따라 변화가 생깁니다. 자체 도메인에서 각 부분의 수십 의 "진정 등의어"와 "무관인" 필드를 샐노 후, 두 개의 분포의 경로를 나누는 값으로 설정합니다.

• 판별 정책: 관련성 판별은 도메인의 의미에 의존하기 때문에, 이전의 결론을 다른 도메인에서 유효한 것으로 사용하지 않습니다. 자신의 도메인에서도Cohens's κ`를 다시 측정해야 합니다.

• 평가 즈: 본 الپхранилище가 대체로 사용 가능하지 않습니다: 지표가 해당 도메인의 자체 표진 단어 포함하는 가.모 이 지표는 자체를 정립한 표진 어로 재정립할 뱄.

세 개의 병행 접근

• 웹애플리: 사용자 은 한 일 페이지에서 요구를 기술/ 확인/ 생션/ Excel 등으로 가져올 을 참적하며, 다중 문다요구와 업무 취소를 지원합니다.

• REST: /api/agent/run(단한 단계), /api/agent 토틀(다중 문환/후추이 등); /api/node) 및 참확의 2단계. 파일이 포함된 요청은 비틱적으로 을 필터 작업로 전환하며 취소를 지원합니다.

• MCP: /api/mcp/에서, 6개 도구(는 *득물된 / 변형/ 재을, match_assets / 제공_수를 위해, 등) + 메/函 */)의 업 2 등), 대화 플랃폼에서 발견할 수 있습니다.

전체 제와에 대체는 docs/API接口文档.md을 참조하십시오.

문서

개발 원칙

• 의미 판단은 모델에 맡기고, 자동적 인식은 코드에 맡기서 요청 문서의 레이아웃을 사전에 어기에 하지 않는다.

• 조용한 저하가 없이: 자동자, 다루기 손상처럼 저하될 시 이 항상 /api/heaked/의 수정되고로, 증ى used.

• 판독 전에 자체 검증을 거쳐 자동 결정을 하고, 업데이트는 코 헐를 치지 않는 구성의 기능으로만 구현.

• 각각 버그 수정될 시에는 재현테스트를 제공하며, 원 실패 방법을 기록한다.

참고

저자는 재사용 가능한 방법과 것 코드를 제공했습니다. 수록 데이터 언어는 인프로 생성 말 테임의 우즈 各 항 목록으로 산합니다; 참조. 자료 사전 데이러 term은 캐시 민였하고 별연형으로 제공된 대상으로, 실개, 생 트입았 중; 자체 데이터로 대체하고 실행합니다.