Upload README.md

README.md

@@ -0,0 +1,361 @@
+---
+language:
+  - ko
+  - en
+  - ja
+  - vi
+library_name: sentence-transformers
+pipeline_tag: feature-extraction
+license: apache-2.0
+tags:
+  - sentence-transformers
+  - multimodal
+  - embedding
+  - finance
+  - retrieval
+  - multilingual
+  - cross-lingual
+  - matryoshka
+  - qwen3-vl
+  - image-text-retrieval
+base_model: Qwen/Qwen3-VL-Embedding-8B
+base_model_relation: finetune
+datasets:
+  - OLAIR/OLA-Embed-Training
+---
+
+# OLA-Embed
+
+OLA-Embed는 금융 문서 검색과 다국어·멀티모달 정보 검색을 위해 개발된 8B 규모의 임베딩 모델입니다. [Qwen3-VL-Embedding-8B](https://huggingface.co/Qwen/Qwen3-VL-Embedding-8B)를 기반으로 금융·경제·뉴스·다국어 pair 데이터에 대해 대조학습을 수행했습니다.
+
+모델은 텍스트, 표가 포함된 문서 이미지, 스크린샷, 이미지, 비디오 및 혼합 입력을 하나의 벡터 공간으로 표현하도록 구성되어 있습니다. 본 과제의 중점 검증 언어는 한국어, 영어, 일본어, 베트남어입니다.
+
+> **라이선스**
+>
+> OLA-Embed는 Apache-2.0 라이선스로 배포됩니다.
+
+## 모델 상세 정보
+
+| 항목 | 내용 |
+|---|---|
+| 모델 저장소 | [OLAIR/OLA-Embed](https://huggingface.co/OLAIR/OLA-Embed) |
+| 개발 기관 | OneLineAI / OLAIR |
+| 기반 모델 | [Qwen/Qwen3-VL-Embedding-8B](https://huggingface.co/Qwen/Qwen3-VL-Embedding-8B) |
+| 모델 유형 | 멀티모달 임베딩 모델 |
+| 파라미터 수 | 8,144,793,840 |
+| 가중치 자료형 | BF16 |
+| 기본 임베딩 차원 | 4,096 |
+| 가변 차원 | 64-4,096 |
+| 유사도 함수 | 코사인 유사도 |
+| 풀링 | 마지막 토큰 풀링 후 L2 정규화 |
+| 중점 검증 언어 | 한국어, 영어, 일본어, 베트남어 |
+| 입력 모달리티 | 텍스트, 이미지, 스크린샷, 비디오, 구조화·혼합 메시지 |
+| 업스트림 문맥 길이 | 32K |
+| 포함된 도우미 기본값 | `max_length=8192`, `fps=1`, `max_frames=64` |
+| 검증한 Hub 리비전 | `2af82c85d92aa1c86afdd12fc4599590a8e3bc1f` |
+
+[업스트림 모델 카드](https://huggingface.co/Qwen/Qwen3-VL-Embedding-8B)와 OLA-Embed의 가변 임베딩 차원 범위는 64-4,096입니다. 실제 운영 전에는 선택한 차원을 자체 검색 말뭉치에서 평가하는 것을 권장합니다.
+
+## 권장 사용 범위
+
+OLA-Embed는 다음 용도로 사용할 수 있습니다.
+
+- 금융 문서 검색 및 의미 기반 검색
+- 공시, 리서치 보고서, 뉴스, 금융 표를 대상으로 하는 RAG 검색
+- 한국어, 영어, 일본어, 베트남어 간 교차언어 검색
+- 텍스트-이미지 및 문서-이미지 검색
+- 의미 유사도 계산, 군집화, 중복 제거, 말뭉치 선별
+- MTEB, 한국어 검색 벤치마크, [M2FEB](https://huggingface.co/datasets/OLAIR/M2FEB)를 이용한 검색 성능 평가
+
+OLA-Embed는 텍스트 생성 모델이나 재정렬 모델이 아닙니다. 금융 자문, 거래, 신용 판단, 법률 해석, 규제 준수 판단의 유일한 근거로 사용해서는 안 됩니다.
+
+## 아키텍처 및 표현 방식
+
+공개 저장소에서 확인되는 추론 구성은 다음과 같습니다.
+
+- 36개 텍스트 레이어와 멀티모달 비전 인코더로 구성된 Qwen3-VL 백본
+- Sentence Transformers 연동
+- 4,096차원 출력 임베딩
+- 마지막 토큰 풀링
+- L2 정규화 임베딩
+- 코사인 유사도
+- 기본 지시문: `Represent the user's input.`
+
+저장소의 `scripts/qwen3_vl_embedding.py`는 하나의 임베딩 인터페이스를 통해 텍스트, 이미지, 비디오 및 혼합 입력을 처리합니다.
+
+## 학습 데이터
+
+학습 데이터는 [OLAIR/OLA-Embed-Training](https://huggingface.co/datasets/OLAIR/OLA-Embed-Training)으로 공개되어 있습니다.
+
+| 항목 | 내용 |
+|---|---|
+| 최종보고서 인증 pair 수 | 2,094,342,001쌍 |
+| [공개 저장소 용량](https://huggingface.co/datasets/OLAIR/OLA-Embed-Training) | 약 2.15TB |
+| Pair 레이블 | Positive pair 및 hard-negative pair |
+| 핵심 필드 | `pair_id`, `label`, `pair_type`, `pair_subtype`, `a_text`, `b_text`, 출처 메타데이터 |
+| 목표 중복도 기준 | 그룹별 평균 ROUGE-L F1 0.4 이하 |
+
+학습 데이터 수량은 최종 전수 검사로 인증한 2,094,342,001쌍을 기준으로 표기했습니다.
+
+### 데이터 출처 및 pair 구성
+
+최종보고서에 기재된 데이터 출처와 변환 방식은 다음과 같습니다.
+
+- 국립국어원 말뭉치 및 AI-Hub 자료를 포함한 공개 한국어 자원
+- 한국거래소, 한국은행, 금융위원회 등의 공개 금융·경제 문서
+- 금융 보고서, 공시, 뉴스, 문서 요약, 웹 말뭉치, 다국어 병렬 말뭉치
+- 의미가 같은 문단, 문장·청크 관계, 요약 관계, 다국어 병렬 관계로 구성한 positive pair
+- 표면적 어휘는 유사하지만 금융 수치, 증감 방향, 기간 또는 의미가 다른 명시적 hard negative
+- 한국어, 영어, 일본어, 베트남어를 중심으로 구성한 교차언�� positive pair
+
+이 모델 카드를 작성한 시점에는 [공개 학습 데이터셋](https://huggingface.co/datasets/OLAIR/OLA-Embed-Training)에 데이터셋 단위 라이선스가 선언되어 있지 않았습니다. 재배포 또는 상업적 이용 전 현재 저장소 메타데이터와 원천별 이용 조건을 확인해야 합니다.
+
+## 학습 방법
+
+### 1. 대조학습
+
+- InfoNCE 손실을 이용한 bi-encoder 미세조정
+- In-batch negative 사용
+- 금융 수치, 증감 방향, 기간 및 근중복 표현을 구분하기 위한 명시적 hard negative 사용
+- 질의에만 태스크 지시문을 적용하는 비대칭적 질의·문서 처리
+
+### 2. Matryoshka Representation Learning
+
+- 여러 임베딩 절단 차원을 동시에 최적화
+- 차원 축소를 통한 벡터 저장 비용 및 검색 비용 절감
+- 기본 출력 차원은 4,096차원
+
+### 3. 레이어 인지형 지식 증류
+
+- 중간 레이어와 최종 레이어의 출력 분포를 KL-divergence로 정렬
+- 차원 축소와 레이어 축소를 함께 지원하도록 설계한 학습 목적함수(2D Matryoshka)
+
+공개 기본 인터페이스는 최종 레이어 임베딩을 반환합니다. 중간 레이어 추출은 별도 연동이 필요하며 기본 Sentence Transformers 풀링 설정에는 노출되어 있지 않습니다.
+
+### 4. 교차언어 정렬
+
+- Understand-Solve-Translate(UST)에서 착안한 영어 앵커 기반 의미 정렬
+- 교차언어 지식 전이를 위한 Language-Mixed CoT 데이터 생성
+- 단순 번역 증강이 아닌 언어별 자연 생성 방식 적용
+
+### 5. 데이터 품질 검증
+
+- 최종 수량과 중복도 검증에 샘플링이 아닌 전수 검사 적용
+- 대규모 ROUGE-L 계산을 위한 비트 병렬 LCS 엔진 사용
+- Python 참조 구현과의 교차 검증
+- 샤드 무결성, 절단 파일, 미완료 파일 검증
+
+## 사용법
+
+### 설치
+
+```bash
+pip install "sentence-transformers>=5.4.0" "transformers>=4.57.1" qwen-vl-utils pillow torch
+```
+
+### Sentence Transformers를 이용한 텍스트 검색
+
+```python
+import torch
+from sentence_transformers import SentenceTransformer
+
+model = SentenceTransformer(
+    "OLAIR/OLA-Embed",
+    device="cuda",
+    trust_remote_code=True,
+    model_kwargs={"torch_dtype": torch.bfloat16},
+)
+
+queries = [
+    "삼성전자의 2024년 영업이익은 전년 대비 어떻게 변했는가?"
+]
+
+documents = [
+    "삼성전자의 2024년 영업이익은 32조 7,260억원으로 전년 대비 크게 증가했다.",
+    "한국의 2024년 실업률은 2.8%였다.",
+    "ORIX의 당기순이익은 FY2026/3에 447,265백만 엔을 기록했다.",
+]
+
+query_instruction = (
+    "사용자 질의에 답할 수 있는 금융 문서를 검색한다."
+)
+
+query_embeddings = model.encode_query(
+    queries,
+    prompt=query_instruction,
+    normalize_embeddings=True,
+    truncate_dim=1024,
+)
+
+document_embeddings = model.encode_document(
+    documents,
+    normalize_embeddings=True,
+    truncate_dim=1024,
+)
+
+scores = model.similarity(query_embeddings, document_embeddings)
+print(scores)
+```
+
+질의와 문서에는 동일한 `truncate_dim`을 사용해야 합니다. 1,024차원 또는 4,096차원부터 시작한 뒤, 검색 품질과 지연시간 요구사항에 따라 더 낮은 차원을 검증하는 방식을 권장합니다.
+
+### 멀티모달 임베딩
+
+Hub 저장소에는 `scripts/qwen3_vl_embedding.py`가 포함되어 있습니다. 전체 [OLAIR/OLA-Embed](https://huggingface.co/OLAIR/OLA-Embed) 저장소를 복제하거나 내려받은 후 저장소 루트에서 다음 코드를 실행할 수 있습니다.
+
+```python
+import torch
+from scripts.qwen3_vl_embedding import Qwen3VLEmbedder
+
+model = Qwen3VLEmbedder(
+    model_name_or_path="OLAIR/OLA-Embed",
+    torch_dtype=torch.bfloat16,
+)
+
+inputs = [
+    {
+        "text": "2024년 영업이익이 증가한 기업의 공시를 검색한다.",
+        "instruction": "검색에 사용할 금융 질의를 표현한다.",
+    },
+    {
+        "image": "annual_report_page.png",
+        "instruction": "검색에 사용할 금융 문서 이미지를 표현한다.",
+    },
+]
+
+embeddings = model.process(inputs, normalize=True)
+similarities = embeddings @ embeddings.T
+print(similarities)
+```
+
+## 평가 결과
+
+아래 결과는 TIPS 최종보고서와 해당 보고서에서 참조한 KOLAS 시험성적서의 수치를 옮긴 것입니다. 평가 재현성을 높이기 위해 동결된 평가 데이터와 태스크별 지시문을 사용했습니다.
+
+### 영어 MTEB
+
+평가는 영어 MTEB 56개 태스크와 2개 이중 텍스트 마이닝 데이터셋을 포함하며, 아래 값은 태스크 유형별 집계 결과입니다.
+
+| 태스크 유형 | 주요 지표 | 목표치 | OLA-Embed |
+|---|---:|---:|---:|
+| 이중 텍스트 마이닝 | F1 | >= 0.680 | **0.886** |
+| 분류 | 정확도 | >= 0.800 | **0.835** |
+| 군집화 | V-measure | >= 0.500 | **0.516** |
+| 쌍 분류 | AP(코사인) | >= 0.880 | **0.886** |
+| 재정렬 | MAP | >= 0.600 | **0.600** |
+| 검색 | nDCG@10 | >= 0.550 | **0.748** |
+| 의미 텍스트 유사도 | Spearman(코사인) | >= 0.850 | **0.851** |
+| 요약 | Spearman(코사인) | >= 0.320 | **0.322** |
+
+### 한국어 검색 벤치마크
+
+평가는 nDCG@10을 사용하는 한국어 검색 태스크 8개와 종합값인 `Korean Average` 1개 행으로 구성됩니다.
+
+| 데이터셋 | 목표치 | OLA-Embed |
+|---|---:|---:|
+| Korean Human Judgements | >= 0.980 | **0.996** |
+| Korean Dialog Summary | >= 0.930 | **0.976** |
+| Korean Summarize AiHub | >= 0.990 | **0.996** |
+| Alpaca-Korean | >= 0.850 | **0.977** |
+| Korean Grade School Math | >= 0.990 | **0.999** |
+| Korean QA Generation | >= 0.900 | **0.935** |
+| Korean RLHF | >= 0.950 | **0.983** |
+| Korean Law Open Data Precedents | >= 0.950 | **0.988** |
+| Korean Average | >= 0.950 | **0.950** |
+
+보고된 성능 측정에 사용한 평가 데이터는 다음과 같습니다.
+
+- [Cartinoe5930/TIPS-English](https://huggingface.co/datasets/Cartinoe5930/TIPS-English)
+- [Cartinoe5930/TIPS-Korean](https://huggingface.co/datasets/Cartinoe5930/TIPS-Korean)
+
+### M2FEB
+
+[OLAIR/M2FEB](https://huggingface.co/datasets/OLAIR/M2FEB)는 CC-BY-4.0으로 공개된 금융 특화 다국어 벤치마크입니다. 구성은 다음과 같습니다.
+
+- 평가 문항 350개
+- 텍스트·표 입력 문맥 700개
+- A/B 선택지 세트 300개
+- 금융 도메인 10개
+- 한국어, 영어, 일본어, 베트남어 문항
+- 문항별 출처 추적 정보와 검증된 금융 수치
+
+최종보고서는 M2FEB를 본 과제의 개발 결과물로 제시합니다. 다만 현재 보고서에는 OLA-Embed의 M2FEB 점수가 포함되어 있지 않으므로 이 모델 카드에서도 해당 성능을 주장하지 않습니다.
+
+## 재현성 참고사항
+
+- 저장소 기본 출력: L2 정규화된 4,096차원 벡터
+- 유사도: 코사인 유사도
+- 기본 프롬프트: `Represent the user's input.`
+- 업스트림 백본은 32K 문맥 길이를 명시하지만 포함된 멀티모달 도우미의 기본값은 8,192토큰
+- 평가 리비전을 고정하고 모델 리비전, 프롬프트, 차원, 자료형, 전처리 설정을 함께 기록
+- 실행 시점마다 평가 데이터를 재구성하지 않도록 공개된 동결 평가 데이터 사용
+
+## 한계
+
+- 보고된 성능은 네 가지 중점 언어와 금융 도메인 사용 사례를 중심으로 검증되었으며, 다른 언어와 도메인에서는 별도 평가가 필요합니다.
+- Qwen3-VL 아키텍처를 통해 이미지와 비디오를 임베딩할 수 있지만, 현재 OLA-Embed 보고서에는 OLA-Embed 전용 멀티모달 벤치마크 점수가 없습니다.
+- 금융 수치, 단위, 회계 기간, 증감 방향은 의미적으로 가까우면서도 서로 다른 답을 요구할 수 있습니다. 운영 환경에서는 명시적 hard-negative 테스트가 필요합니다.
+- OCR 품질, 고밀도 표, 저해상도 스크린샷, 비정형 문서 레이아웃은 검색 품질을 낮출 수 있습니다.
+- 임베딩 차원을 줄이면 저장 비용과 지연시간은 감소하지만 검색 정확도도 달라질 수 있으므로 선택한 모든 차원을 검증해야 합니다.
+- BF16 가중치 파일은 실행 부가 메모리를 제외하고 약 16.3GB를 차지합니다. 메모리 사용량은 배치 크기, 문맥 길이, 이미지 해상도, 비디오 프레임 수에 따라 증가합니다.
+- 모델은 원천 말뭉치에 포함된 편향, 오류 또는 민감한 내용을 재현할 수 있습니다.
+- 이 모델은 사실 정확성을 보장하지 않으며 금융, 법률, 회계 또는 규제 검토를 대신할 수 없습니다.
+
+## 안전하고 책임 있는 사용
+
+- 투자, 신용, 보험, 채용 또는 규제 준수 판단의 유일한 의사결정 시스템으로 사용하지 마세요.
+- 기밀 금융 문서를 색인할 때는 접근 제어를 적용하세요.
+- 임베딩을 저장하거나 재배포하기 전에 원천 라이선스와 개인정보 보호 요구사항을 확인하세요.
+- 실제 서비스에 관련된 언어, 문서 유형, 고객군, 기간별로 검색 품질을 평가하세요.
+- 오래된 공시, 정정 공시, 단위 불일치, 날짜 정보 누출을 지속적으로 점검하세요.
+
+## 공개되지 않은 학습·환경 정보
+
+현재 공개 자료에는 다음 정보가 포함되어 있지 않습니다.
+
+- 학습률 및 옵티마이저 스케줄
+- 전체 배치 크기
+- 학습 에폭 또는 최적화 스텝 수
+- 학습 하드웨어와 학습 시간
+- 에너지 사용량 또는 탄소 배출량
+
+해당 정보가 확보되면 모델 카드에 추가하는 것을 권장합니다.
+
+## 라이선스
+
+OLA-Embed는 Apache-2.0 라이선스로 배포됩니다.
+
+업스트림 [Qwen3-VL-Embedding-8B](https://huggingface.co/Qwen/Qwen3-VL-Embedding-8B)는 Apache-2.0으로 공개되어 있으며, [M2FEB](https://huggingface.co/datasets/OLAIR/M2FEB)는 CC-BY-4.0으로 공개되어 있습니다. 학습 데이터의 원천�� 이용 조건은 서로 다를 수 있습니다.
+
+## 인용
+
+OLA-Embed를 사용한 경우 다음과 같이 모델 저장소를 인용해 주세요.
+
+```bibtex
+@misc{olaembed2026,
+  title        = {OLA-Embed},
+  author       = {OneLineAI},
+  year         = {2026},
+  howpublished = {\url{https://huggingface.co/OLAIR/OLA-Embed}}
+}
+```
+
+업스트림 Qwen3-VL-Embedding 연구도 함께 인용해 주세요.
+
+```bibtex
+@article{qwen3vlembedding,
+  title   = {Qwen3-VL-Embedding and Qwen3-VL-Reranker: A Unified Framework for State-of-the-Art Multimodal Retrieval and Ranking},
+  author  = {Li, Mingxin and Zhang, Yanzhao and Long, Dingkun and Chen, Keqin and Song, Sibo and Bai, Shuai and Yang, Zhibo and Xie, Pengjun and Yang, An and Liu, Dayiheng and Zhou, Jingren and Lin, Junyang},
+  journal = {arXiv preprint arXiv:2601.04720},
+  year    = {2026}
+}
+```
+
+## 문의
+
+- 기관: [OLAIR](https://huggingface.co/OLAIR)
+- 웹사이트: [OneLineAI](https://www.onelineai.com/en/)
+
+## 연구개발 배경
+
+OLA-Embed는 금융 특화 멀티모달·다국어 임베딩 모델을 적용한 금융 생성형 AI 솔루션 개발을 목표로 하는 TIPS 연구개발 과제의 결과물로 개발되었습니다.