RAGFlow

RAGFlow

RAGFlow의 채팅 완성 API를 LiteLLM에서 사용하는 방법을 알아봐요. 채팅과 에이전트 엔드포인트를 모두 지원해요.

출처: 문서

본문

LiteLLM은 RAGFlow의 채팅 완성 API를 지원해요.

지원 기능

  • ✅ 채팅 완성 (Chat completions)
  • ✅ 스트리밍 응답
  • ✅ 채팅과 에이전트 엔드포인트 모두
  • ✅ 여러 자격 증명 소스 (params, env vars, litellm_params)
  • ✅ OpenAI 호환 API 형식

API 키

# env variable
os.environ['RAGFLOW_API_KEY']

API Base

# env variable
os.environ['RAGFLOW_API_BASE']

개요

RAGFlow는 채팅 ID와 에이전트 ID를 포함하는 고유한 경로 구조를 가진 OpenAI 호환 API를 제공해요:

  • 채팅 엔드포인트: /api/v1/chats_openai/{chat_id}/chat/completions
  • 에이전트 엔드포인트: /api/v1/agents_openai/{agent_id}/chat/completions

모델 이름 형식은 엔드포인트 타입과 ID를 내장해요:

  • 채팅: ragflow/chat/{chat_id}/{model_name}
  • 에이전트: ragflow/agent/{agent_id}/{model_name}

사용 예시 - 채팅 엔드포인트

from litellm import completion
import os

os.environ['RAGFLOW_API_KEY'] = "your-ragflow-api-key"
os.environ['RAGFLOW_API_BASE'] = "http://localhost:9380"  # or your hosted URL

response = completion(
    model="ragflow/chat/my-chat-id/gpt-5.6-luna",
    messages=[{"role": "user", "content": "How does the deep doc understanding work?"}]
)
print(response)

사용 예시 - 에이전트 엔드포인트

from litellm import completion
import os

os.environ['RAGFLOW_API_KEY'] = "your-ragflow-api-key"
os.environ['RAGFLOW_API_BASE'] = "http://localhost:9380"  # or your hosted URL

response = completion(
    model="ragflow/agent/my-agent-id/gpt-5.6-luna",
    messages=[{"role": "user", "content": "What are the key features?"}]
)
print(response)

사용 예시 - 파라미터 포함

api_key와 api_base를 파라미터로 직접 전달할 수도 있어요:

from litellm import completion

response = completion(
    model="ragflow/chat/my-chat-id/gpt-5.6-luna",
    messages=[{"role": "user", "content": "Hello!"}],
    api_key="your-ragflow-api-key",
    api_base="http://localhost:9380"
)
print(response)

사용 예시 - 스트리밍

from litellm import completion
import os

os.environ['RAGFLOW_API_KEY'] = "your-ragflow-api-key"
os.environ['RAGFLOW_API_BASE'] = "http://localhost:9380"

response = completion(
    model="ragflow/agent/my-agent-id/gpt-5.6-luna",
    messages=[{"role": "user", "content": "Explain RAGFlow"}],
    stream=True
)

for chunk in response:
    print(chunk)

모델 이름 형식

모델 이름은 다음 형식 중 하나를 따라야 해요:

채팅 엔드포인트

ragflow/chat/{chat_id}/{model_name}

예시: ragflow/chat/my-chat-id/gpt-5.6-luna

에이전트 엔드포인트

ragflow/agent/{agent_id}/{model_name}

예시: ragflow/agent/my-agent-id/gpt-5.6-luna

여기서:

  • {chat_id} 또는 {agent_id}는 RAGFlow의 채팅 또는 에이전트 ID
  • {model_name}은 실제 모델 이름 (예: gpt-5.6-luna, gpt-5.6-terra 등)

설정 소스

LiteLLM은 여러 방식으로 자격 증명을 지원하며 다음 순서로 확인해요:

  • 함수 파라미터: api_key="...", api_base="..."
  • litellm_params: litellm_params={"api_key": "...", "api_base": "..."}
  • 환경 변수: RAGFLOW_API_KEY, RAGFLOW_API_BASE
  • 전역 litellm 설정: litellm.api_key, litellm.api_base

LiteLLM Proxy 서버 사용법

1. 환경에 키 저장

export RAGFLOW_API_KEY="your-ragflow-api-key"
export RAGFLOW_API_BASE="http://localhost:9380"

2. Proxy 시작

config.yaml:

model_list:
  - model_name: ragflow-chat-gpt4
    litellm_params:
      model: ragflow/chat/my-chat-id/gpt-5.6-luna
      api_key: os.environ/RAGFLOW_API_KEY
      api_base: os.environ/RAGFLOW_API_BASE
  - model_name: ragflow-agent-gpt4
    litellm_params:
      model: ragflow/agent/my-agent-id/gpt-5.6-luna
      api_key: os.environ/RAGFLOW_API_KEY
      api_base: os.environ/RAGFLOW_API_BASE

$ litellm --config /path/to/config.yaml

# Server running on http://0.0.0.0:4000

3. 테스트

curl http://0.0.0.0:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "ragflow-chat-gpt4",
    "messages": [
      {"role": "user", "content": "How does RAGFlow work?"}
    ]
  }'

from openai import OpenAI

client = OpenAI(
    api_key="sk-",  # Your LiteLLM proxy key
    base_url="http://0.0.0.0:4000"
)

response = client.chat.completions.create(
    model="ragflow-chat-gpt4",
    messages=[
        {"role": "user", "content": "How does RAGFlow work?"}
    ]
)
print(response)

API Base URL 처리

api_base 파라미터는 /v1 접미사 유무와 무관하게 제공할 수 있으며, LiteLLM이 자동으로 처리해요:

  • http://localhost:9380 → http://localhost:9380/api/v1/chats_openai/{chat_id}/chat/completions
  • http://localhost:9380/v1 → http://localhost:9380/api/v1/chats_openai/{chat_id}/chat/completions
  • http://localhost:9380/api/v1 → http://localhost:9380/api/v1/chats_openai/{chat_id}/chat/completions

세 형식 모두 올바르게 동작해요.

오류 처리

오류가 발생하면:

  • 잘못된 모델 형식: 모델명이 ragflow/{chat|agent}/{id}/{model_name} 형식을 따르는지 확인
  • api_base 누락: 파라미터, 환경 변수, litellm_params로 api_base 제공
  • 연결 오류: 제공된 api_base에서 RAGFlow 서버가 실행 중이고 접근 가능한지 확인

info: 제공사 전용 파라미터 전달에 대한 자세한 내용은 여기를 참고해요.

더 알아보기 (Learn more)

  • RAGFlow 공식 문서
  • LiteLLM 컴플리션 API