RAGFlow 벡터 스토어

RAGFlow 벡터 스토어 (Vector Stores)

RAGFlow의 데이터셋 생성·관리를 LiteLLM에서 사용하는 방법을 알아봐요. 문서 처리와 지식 베이스 관리를 지원해요.

출처: 문서

본문

LiteLLM은 RAGFlow에서 문서 처리와 지식 베이스 관리를 위한 데이터셋 생성 및 관리를 지원해요.

속성	내용
설명	RAGFlow 데이터셋은 RAG 애플리케이션을 위한 문서 처리, 청킹, 지식 베이스 관리를 가능하게 해요
LiteLLM 라우트	litellm vector_store_registry의 ragflow
공식 문서	RAGFlow API Documentation ↗
지원 연산	데이터셋 관리 (생성, 목록, 업데이트, 삭제)
검색/검색	❌ 미지원 (관리 전용)

빠른 시작

LiteLLM Python SDK

import os
import litellm

# Set RAGFlow credentials
os.environ["RAGFLOW_API_KEY"] = "your-ragflow-api-key"
os.environ["RAGFLOW_API_BASE"] = "http://localhost:9380"  # Optional, defaults to localhost:9380

# Create a RAGFlow dataset
response = litellm.vector_stores.create(
    name="my-dataset",
    custom_llm_provider="ragflow",
    metadata={
        "description": "My knowledge base dataset",
        "embedding_model": "BAAI/bge-large-zh-v1.5@BAAI",
        "chunk_method": "naive"
    }
)

print(f"Created dataset ID: {response.id}")
print(f"Dataset name: {response.name}")

LiteLLM Proxy

1. vector_store_registry 구성

config.yaml:

model_list:
  - model_name: gpt-5.6-luna
    litellm_params:
      model: gpt-5.6-luna
      api_key: os.environ/OPENAI_API_KEY

vector_store_registry:
  - vector_store_name: "ragflow-knowledge-base"
    litellm_params:
      vector_store_id: "your-dataset-id"
      custom_llm_provider: "ragflow"
      api_key: os.environ/RAGFLOW_API_KEY
      api_base: os.environ/RAGFLOW_API_BASE  # Optional
      vector_store_description: "RAGFlow dataset for knowledge base"
      vector_store_metadata:
        source: "Company documentation"

LiteLLM UI에서는 Experimental > Vector Stores > Create Vector Store로 이동해 이름, 벡터 스토어 ID, 자격 증명으로 벡터 스토어를 만들 수 있어요.

2. Proxy를 통해 데이터셋 생성

curl http://localhost:4000/v1/vector_stores \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "name": "my-ragflow-dataset",
    "custom_llm_provider": "ragflow",
    "metadata": {
      "description": "Test dataset",
      "chunk_method": "naive"
    }
  }'

from openai import OpenAI

# Initialize client with your LiteLLM proxy URL
client = OpenAI(
    base_url="http://localhost:4000",
    api_key="your-litellm-api-key"
)

# Create a RAGFlow dataset
response = client.vector_stores.create(
    name="my-ragflow-dataset",
    custom_llm_provider="ragflow",
    metadata={
        "description": "Test dataset",
        "chunk_method": "naive"
    }
)

print(f"Created dataset: {response.id}")

구성

환경 변수

RAGFlow 벡터 스토어는 환경 변수를 통한 구성을 지원해요:

• RAGFLOW_API_KEY - RAGFlow API 키 (필수)
• RAGFLOW_API_BASE - RAGFlow API base URL (선택, 기본값 http://localhost:9380)

파라미터

litellm_params로도 전달할 수 있어요:

• api_key - RAGFlow API 키 (RAGFLOW_API_KEY env var 덮어씀)
• api_base - RAGFlow API base URL (RAGFLOW_API_BASE env var 덮어씀)

데이터셋 생성 옵션

기본 데이터셋 생성

response = litellm.vector_stores.create(
    name="basic-dataset",
    custom_llm_provider="ragflow"
)

청크 메서드가 있는 데이터셋

RAGFlow는 문서 유형에 따라 다양한 청크 메서드를 지원해요:

• Naive (일반)
• Book
• Q&A
• Paper

response = litellm.vector_stores.create(
    name="general-dataset",
    custom_llm_provider="ragflow",
    metadata={
        "chunk_method": "naive",
        "parser_config": {
            "chunk_token_num": 512,
            "delimiter": "\n",
            "html4excel": False,
            "layout_recognize": "DeepDOC"
        }
    }
)

response = litellm.vector_stores.create(
    name="book-dataset",
    custom_llm_provider="ragflow",
    metadata={
        "chunk_method": "book",
        "parser_config": {
            "raptor": {
                "use_raptor": False
            }
        }
    }
)

response = litellm.vector_stores.create(
    name="qa-dataset",
    custom_llm_provider="ragflow",
    metadata={
        "chunk_method": "qa",
        "parser_config": {
            "raptor": {
                "use_raptor": False
            }
        }
    }
)

response = litellm.vector_stores.create(
    name="paper-dataset",
    custom_llm_provider="ragflow",
    metadata={
        "chunk_method": "paper",
        "parser_config": {
            "raptor": {
                "use_raptor": False
            }
        }
    }
)

인제스트 파이프라인이 있는 데이터셋

청크 메서드 대신 인제스트 파이프라인을 사용할 수 있어요:

response = litellm.vector_stores.create(
    name="pipeline-dataset",
    custom_llm_provider="ragflow",
    metadata={
        "parse_type": 2,  # Number of parsers in your pipeline
        "pipeline_id": "d0bebe30ae2211f0970942010a8e0005"  # 32-character hex ID
    }
)

참고: chunk_method와 pipeline_id는 상호 배타적이에요. 둘 중 하나만 사용해요.

고급 파서 구성

response = litellm.vector_stores.create(
    name="advanced-dataset",
    custom_llm_provider="ragflow",
    metadata={
        "chunk_method": "naive",
        "description": "Advanced dataset with custom parser config",
        "embedding_model": "BAAI/bge-large-zh-v1.5@BAAI",
        "permission": "me",  # or "team"
        "parser_config": {
            "chunk_token_num": 1024,
            "delimiter": "\n!?;。；！？",
            "html4excel": True,
            "layout_recognize": "DeepDOC",
            "auto_keywords": 5,
            "auto_questions": 3,
            "task_page_size": 12,
            "raptor": {
                "use_raptor": True
            },
            "graphrag": {
                "use_graphrag": False
            }
        }
    }
)

지원 청크 메서드

RAGFlow는 다음 청크 메서드를 지원해요:

• naive - 일반 용도 (기본값)
• book - 책 문서용
• email - 이메일 문서용
• laws - 법률 문서용
• manual - 수동 청킹
• one - 단일 청크
• paper - 학술 논문용
• picture - 이미지 문서용
• presentation - 프레젠테이션 문서용
• qa - Q&A 형식
• table - 표 문서용
• tag - 태그 기반 청킹

RAGFlow 전용 파라미터

모든 RAGFlow 전용 파라미터는 metadata 필드를 통해 전달해야 해요:

파라미터	타입	설명
avatar	string	아바타의 Base64 인코딩 (최대 65535자)
description	string	데이터셋에 대한 간단한 설명 (최대 65535자)
embedding_model	string	임베딩 모델 이름 (예: "BAAI/bge-large-zh-v1.5@BAAI")
permission	string	접근 권한: "me" (기본값) 또는 "team"
chunk_method	string	청킹 메서드 (위 지원 메서드 참조)
parser_config	object	파서 구성 (chunk_method에 따라 다름)
parse_type	int	파이프라인의 파서 수 (pipeline_id와 함께 필수)
pipeline_id	string	32자 16진수 파이프라인 ID (parse_type과 함께 필수)

오류 처리

RAGFlow는 다음 형식으로 오류 응답을 반환해요:

{
    "code": 101,
    "message": "Dataset name 'my-dataset' already exists"
}

LiteLLM은 이를 적절한 예외로 자동 매핑해요:

• code != 0 → 오류 메시지와 함께 예외 발생
• 필수 필드 누락 → ValueError 발생
• 상호 배타적 파라미터 → ValueError 발생

제한 사항

• 검색/검색: RAGFlow 벡터 스토어는 데이터셋 관리만 지원해요. 검색 연산은 미지원이며 NotImplementedError를 발생시켜요.
• 목록/업데이트/삭제: 이러한 연산은 아직 표준 벡터 스토어 API로 구현되지 않았어요. RAGFlow 네이티브 API 엔드포인트를 직접 사용해요.

더 알아보기 (Learn more)

• 벡터 스토어 생성
• 컴플리션과 벡터 스토어 사용
• 벡터 스토어 레지스트리