OpenAI-API-Compatible base URL로 RAGFlow 채팅 실행하기.

빠른 답: Model providers 페이지에서 모델 추가하기.

RAGFlow에 로그인해 오른쪽 위 로고를 클릭하고 Model providers를 여세요. Models to be added 아래에서 OpenAI-API-Compatible 카드를 찾아 Add the model을 클릭하세요. Add LLM 다이얼로그에서 Model type을 chat으로 설정하고, 정확한 카탈로그 id를 Model name으로 입력하고, https://api.apisrouter.com/v1을 Base url에 넣고, 키를 API-Key에 붙여넣은 다음, Max tokens를 모델의 실제 컨텍스트 크기로 설정하세요. OK를 클릭하세요. 그런 다음 무언가 하게 만드세요: 같은 페이지에서 Set default models를 열어 새 모델을 기본 LLM으로 선택하세요. 채팅 어시스턴트, 데이터셋 질문 답변, 에이전트 노드는 모두 오버라이드하지 않는 한 그 기본값으로 해석됩니다. 첫 실행 전에 알아둘 날카로운 모서리 하나: RAGFlow의 Max tokens 필드는 기본값이 512이고 그 자체 툴팁이 잘못된 값이 오류를 일으킨다고 경고합니다. 모델의 문서화된 윈도우를 입력하는 것은 최적화가 아니라 설정의 일부입니다.

Model type:  chat
Model name:  deepseek-v4-pro
Base url:    https://api.apisrouter.com/v1
API-Key:     sk-YOUR-APISROUTER-KEY
Max tokens:  128000

then: Set default models → LLM → deepseek-v4-pro

RAGFlow가 모델을 작업에 바인딩하는 방식.

RAGFlow(GitHub의 infiniflow, 약 8.5만 스타)는 깊이 있는 문서 RAG 엔진입니다: PDF와 표에 대한 레이아웃 인식 파싱, 근거를 갖춘 인용이 있는 청킹, 데이터셋, 채팅 어시스턴트, 그리고 그 위의 에이전트 워크플로우. 그 파이프라인의 서로 다른 부분이 서로 다른 모델 슬롯에 바인딩되며, 그 바인딩은 명시적입니다. 채팅 모델은 답변을 생성합니다. 임베딩 모델은 검색을 위해 청크를 벡터화합니다. 리랭크 모델은 후보의 순서를 다시 매기고, img2txt 모델은 파싱 중 그림을 설명합니다. OpenAI-API-Compatible 프로바이더는 이 타입들 각각에 대해 개별적으로 모델을 등록할 수 있으며, 각 Add LLM 다이얼로그가 타입, id, base url, 키의 바인딩 하나를 만듭니다. 등록된 모든 채팅 모델은 Model name을 와이어 문자열로 하여 base url에 표준 chat completions로 말하므로, 게이트웨이가 서빙하는 어떤 id도 벤더와 상관없이 유효합니다. 이 분리는 운영상 중요합니다: 답변 모델을 gpt-5.5에서 claude-sonnet-4-6으로 바꾸는 것은 언제든 안전하지만, 임베딩 모델은 인덱싱된 벡터에 용접되어 있습니다. RAGFlow는 이미 청크가 있는 데이터셋에서 임베딩 모델을 전환할 때 호환성 체크로 이를 강제하며, 실용적인 규칙은 더 단순합니다: 임베딩 설정은 한 번 고르고, 채팅 모델은 자유롭게 조정할 레이어로 취급하세요.

중국 모델과 서구 모델을 위한 키 하나.

RAGFlow 배포는 이중 언어에 치우쳐 있습니다: 중국어권 팀이 다국어 문서 베이스를 처리하고, 국제 팀이 중국어 문서를 위해 특별히 중국 모델을 원합니다. 직접 연결하면 이 조합은 고통스럽습니다. DeepSeek, Zhipu, Moonshot, Alibaba가 각각 따로 청구되고 일부는 해외에서 결제하기 어색하며, Anthropic과 OpenAI는 반대 방향에서 어색하기 때문입니다. OpenAI-API-Compatible base url 하나를 통하면 이 조합은 그저 더 많은 Add LLM 다이얼로그일 뿐입니다: 중국어 중심 코퍼스에는 deepseek-v4-pro와 glm-5.2, 강력한 지역 대안으로 qwen3.7-max와 kimi-k2.6, 답변 완성도가 가장 중요한 곳에는 claude-sonnet-4-6. 같은 base url, 같은 키, 카탈로그에서 바로 가져온 id. 아시아의 팀에게는 같은 경로가 반대로도 작동합니다: Claude와 GPT id가 서구 카드 없이 선불 잔액으로 도달 가능해지는데, 많은 RAGFlow 사용처에서 이는 모델을 평가하는 것과 그것에 대해 읽기만 하는 것의 차이입니다. 첫 부팅 시점의 경로도 알아둘 가치가 있습니다: service_conf.yaml.template은 user_default_llm 블록(factory, api_key, base_url)을 받으므로 새 설치가 미리 배선된 채로 올라옵니다. RAGFlow의 문서는 로그인 이후에는 설정이 Model providers 페이지에서만 일어난다고 명시하므로, YAML은 첫 부팅 프로비저닝으로 취급하고 실시간 설정으로 취급하지 마세요.

user_default_llm:
  factory: OpenAI-API-Compatible
  api_key: sk-YOUR-APISROUTER-KEY
  base_url: https://api.apisrouter.com/v1

문서 파이프라인을 위한 모델 선택.

검색 품질이 상한선을 정하고 답변 모델이 얼마나 그 상한에 가까워지는지를 결정하므로, 여러분의 실제 코퍼스에서 답변 모델을 A/B 테스트하세요: 같은 데이터셋, 같은 질문, 두 id에 고정된 두 어시스턴트, 그리고 답변에 대한 여러분 자신의 판단 옆에 놓인 APIsRouter 콘솔의 모델별 지출.

• 검색된 청크에 대한 근거 답변은 입력이 많은 작업이며 중간 티어 모델이 빛을 발하는 곳입니다: deepseek-v4-pro와 glm-5.2는 다국어 코퍼스에서 인용을 따라가는 답변을 잘 처리합니다.
• qwen3.7-max와 kimi-k2.6은 답변이 중국어로 자연스럽게 읽혀야 할 때 테스트할 가치가 있는 지역 헤비웨이트입니다; 중국 모델 간 품질 차이는 검색보다 생성에서 더 드러납니다.
• claude-sonnet-4-6은 합성 품질이 곧 제품인 곳, 즉 임원 요약, 계약서 분석, 사람이 수정 없이 전달하는 모든 것을 위한 답변 슬롯을 받을 자격이 있습니다.
• 툴을 호출하는 에이전트 워크플로우는 믿을 만한 함수 호출이 필요합니다; 먼저 claude-sonnet-4-6으로 에이전트 경로를 테스트한 다음 어떤 지역 id가 여러분의 플로우에서 그것과 맞먹는지 확인하세요.
• Max tokens는 등록별로 설정되므로, 한 어시스턴트는 긴 답변이 필요하고 다른 하나는 짧은 답변이 필요하다면 같은 id를 다른 한도로 두 번 등록하세요.

사용한 만큼 지불 · 공식 요금보다 저렴

Selected models are priced below official list prices. Exact input, output, cache, and per-request prices are shown for each model.

RAGFlow 특유의 실패 패턴.

Max tokens 기본값이 전형적인 문제입니다. 512로 두면 긴 답변이 모델 문제처럼 보이는 방식으로 잘리거나 오류가 납니다; 등록할 때 툴팁 자체가 경고하는 대로 문서화된 컨텍스트 크기를 설정하세요. 등록된 모델이 즉시 오류를 낸다면 보통 Model name 표기(/v1/models 목록과 정확히 일치해야 함) 또는 /v1 접미사가 빠진 Base url 문제입니다. RAGFlow가 입력한 것에 라우트 경로를 덧붙이기 때문입니다. 등록 후 아무 일도 일어나지 않는 것은 기본값 문제입니다: 모델을 등록해도 선택되지는 않습니다. Set default models를 확인하고, 워크스페이스 기본값을 오버라이드하는 어시스턴트별 모델 설정도 확인하세요. 임베딩 혼란이 목록을 마무리합니다. 호환 프로바이더를 통해 임베딩 id를 바인딩한다면 인덱싱 전에 엔드포인트가 실제로 그것을 서빙하는지 확인하세요; 데이터셋에 청크가 생기고 나면 임베딩 모델 변경은 유사도 체크로 게이트되며 처음부터 재인덱싱이 필요할 수 있습니다. 채팅 모델 변경에는 그런 비용이 없으며, 정확히 그래서 채팅 레이어가 실험해야 할 곳입니다.

어떤 사람들이 게이트웨이를 통해 RAGFlow를 쓰는가.

• DeepSeek, GLM, Qwen, Kimi를 Claude, GPT id와 하나의 base url과 키 뒤에서 섞는 이중 언어 문서 팀.
• 서구 카드 없이 선불 잔액으로 Claude급 답변을 원하는 아시아의 팀, 그리고 지역 청구 없이 중국 모델을 원하는 서구의 팀.
• OneAPI 사이드카를 대체하는 셀프 호스터 — 게이트웨이가 멀티벤더 부분을, RAGFlow의 내장 채널이 라우팅 부분을 서빙합니다.
• 고정된 코퍼스에서 답변 모델을 비교하는 빌더 — 각 후보는 벤더 계정이 아니라 Add LLM 다이얼로그 하나일 뿐입니다.
• service_conf.yaml.template에서 엔드포인트를 미리 배선한 채로 새 설치를 프로비저닝하는 운영팀.

엔드포인트 검증 및 첫 채팅 디버깅.

모델 목록을 먼저 curl로 확인하세요; Model name 필드는 자유 텍스트이므로 목록에서 id를 복사하면 가장 흔한 실패를 미리 제거할 수 있습니다. 그런 다음 등록하려는 id를 대상으로 채팅 완성을 한 번 실행하세요. RAGFlow 내부에서는 모델을 등록하고, 기본 LLM으로 설정한 다음, 데이터셋을 관여시키기 전에 일반 채팅 어시스턴트에서 테스트하세요. 인증 오류는 API-Key를 가리킵니다; not-found는 Model name을; 연결 오류는 Base url이나 컨테이너 이그레스를 가리킵니다(브라우저가 아니라 RAGFlow 서버가 엔드포인트에 도달해야 하기 때문입니다). 잘리거나 실패하는 긴 답변은 다시 Max tokens를 가리킵니다. 채팅이 흐르기 시작하면 APIsRouter 콘솔에서 요청별 모델, 토큰 수, 지출을 볼 수 있습니다. RAG 트래픽은 입력이 지배적이며, 사용량 로그는 여러분의 코퍼스가 모델별, 날짜별로 질의하는 데 실제로 얼마나 드는지, 중국과 서구 id가 한 페이지에 함께 나온 것을 보는 곳입니다.

curl -s https://api.apisrouter.com/v1/models \
  -H "Authorization: Bearer $APISROUTER_API_KEY" | head -50

curl -s https://api.apisrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $APISROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro",
       "messages":[{"role":"user","content":"ping"}]}'

자주 묻는 질문