gpt-researcher를 커스텀 OpenAI 호환 엔드포인트에서 실행하기.

빠른 답: 다섯 줄짜리 .env 블록.

gpt-researcher가 문서화한 커스텀 엔드포인트 경로는 환경 변수입니다. OPENAI_BASE_URL을 https://api.apisrouter.com/v1로, OPENAI_API_KEY를 여러분의 게이트웨이 키로 설정하고, openai: 프로바이더 접두어로 세 모델 슬롯을 지정하세요. 접두어가 gpt-researcher에게 어떤 클라이언트를 쓸지 알려줍니다; 콜론 뒤의 문자열은 그대로 엔드포인트에 전달되므로, 게이트웨이가 서빙하는 어떤 id든 유효합니다, Claude와 Gemini id도 포함해서요. 이는 커스텀 OpenAI 호환 엔드포인트를 위해 docs.gptr.dev에 문서화된 설정이며, pip 패키지, 웹 앱, 멀티 에이전트 플로우 모두에서 동일하게 작동합니다. 모두가 같은 설정을 해석하기 때문입니다.

OPENAI_BASE_URL=https://api.apisrouter.com/v1
OPENAI_API_KEY=sk-APIsRouter-...
FAST_LLM=openai:claude-haiku-4-5-20251001
SMART_LLM=openai:claude-sonnet-4-6
STRATEGIC_LLM=openai:gpt-5.5

gpt-researcher가 세 슬롯에 토큰을 쓰는 방식.

gpt-researcher(GitHub의 assafelovic, 약 2.8만 스타)는 질의를 리서치된, 출처가 명시된 보고서로 바꿉니다: 리서치 질문을 계획하고, 리트리버를 통해 웹 검색을 분산시키고, 출처를 스크랩하고 요약한 다음, 장문 보고서를 작성합니다. 이 프레임워크는 그 파이프라인을 하나가 아니라 세 개의 설정 가능한 모델 슬롯으로 나눕니다. FAST_LLM은 고물량, 저위험 작업, 주로 스크랩된 페이지 요약을 처리합니다. SMART_LLM은 최종 보고서를 포함한 무거운 작문을 합니다. STRATEGIC_LLM은 계획을 담당합니다: 리서치 질문을 생성하고 접근 방식을 정합니다. 기본값은 그대로 OpenAI 모델(작성 시점 기준 각각 gpt-4o-mini, gpt-4.1, o4-mini)인데, 바로 이 때문에 OPENAI_BASE_URL 오버라이드 하나가 그토록 효과적입니다: 세 슬롯 모두 OpenAI 형태의 클라이언트를 쓰므로, base URL 하나가 전체 파이프라인을 옮깁니다. 각 슬롯이 자체 provider:model 문자열을 받으므로, 슬롯들이 벤더를 공유할 필요가 없습니다. 한 번의 실행이 빠른 Claude 모델로 요약하고, 더 강한 Claude나 GPT 모델로 작성하고, 추론 티어 모델로 계획하는 것을 같은 엔드포인트와 키를 통해 모두 할 수 있습니다. 단일 벤더 키에서는 그런 조합에 계정 세 개가 필요하지만, 게이트웨이 뒤에서는 .env의 세 줄이면 됩니다.

전체 설정: .env와 Python API.

작업 디렉터리에 .env 파일을 만들거나(또는 셸에서 변수를 export하고) 평소처럼 gpt-researcher를 실행하세요; pip 패키지와 웹 앱 모두 같은 환경을 읽습니다. Python API는 엔드포인트 전용 코드가 전혀 필요 없는데, 그것이 핵심입니다: 라우팅은 설정이며, 엔드포인트가 OpenAI든 게이트웨이든 리서치 코드는 그대로입니다. 인접한 두 설정이 중요합니다. 웹 검색은 자체 키(TAVILY_API_KEY)를 가진 리트리버(기본값 Tavily)를 통해 실행됩니다; 그 자격 증명은 LLM 엔드포인트와 독립적이며 실시간 웹 리서치에 여전히 필요합니다. 그리고 임베딩은 기본값이 openai:text-embedding-3-small인데, 이는 임베딩 호출도 같은 OpenAI 형태의 클라이언트 설정을 따른다는 뜻입니다; OPENAI_BASE_URL 뒤의 엔드포인트가 그 임베딩 모델을 서빙하지 않는다면, EMBEDDING을 서빙하는 프로바이더로 명시적으로 설정하세요(문서는 OpenAI 호환 임베딩 엔드포인트에 custom: 접두어를 쓰며, Ollama 같은 로컬 옵션도 지원됩니다).

import asyncio
from gpt_researcher import GPTResearcher

async def main():
    researcher = GPTResearcher(
        query="State of small modular reactors in 2026",
        report_type="research_report",
    )
    await researcher.conduct_research()
    report = await researcher.write_report()
    print(report)

asyncio.run(main())  # routing comes entirely from .env

슬롯별 모델 선택.

업스트림 기본값은 올바른 형태를 부호화합니다: 물량용 작은 모델, 작문용 강한 모델, 계획용 추론 모델, 그러니 그 형태를 유지하고 하나의 모델로 평평하게 만들기보다 슬롯을 업그레이드하세요. 엔드포인트 하나 뒤에서 두 작가 모델 간 A/B는 실행마다 .env 한 줄 변경이며, 키별 사용량 로그가 각 보고서 설정이 실제로 얼마였는지 알려줍니다.

• FAST_LLM이 가장 많이 발동합니다: 스크랩된 모든 출처가 요약됩니다. 빠른 id(claude-haiku-4-5-20251001, deepseek-v4-flash)는 출처가 많은 보고서가 요약 비용에 지배당하지 않게 해주며, 요약은 독자가 아니라 작가에게 먹이가 되므로 여기서의 품질 손실은 제한적입니다.
• SMART_LLM은 사용자가 실제로 읽는 보고서를 씁니다. 긴 출력, 지속되는 구조, 인용 규율: 여기가 claude-sonnet-4-6이나 gpt-5.5가 그 비용값을 하는 곳이고, 품질을 낮추면 즉시 티가 나는 곳입니다.
• STRATEGIC_LLM은 실행이 시작되기 전에 그 형태를 잡습니다. 작가가 아무리 뛰어나도 나쁜 리서치 질문은 나쁜 보고서를 만듭니다; 여기서 추론에 강한 모델은 호출은 적지만 레버리지가 큽니다.
• gemini-3.1-pro-preview 같은 롱컨텍스트 id는 작가가 누적된 요약의 큰 컨텍스트를 다루는 detailed_report 실행에서 SMART 슬롯으로 테스트할 가치가 있습니다.

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

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

gpt-researcher에 특유한 실패 패턴.

프로바이더 접두어를 빼먹는 경우. 슬롯 형식은 provider:model이며, 접두어가 클라이언트를 선택합니다. openai: 없이 SMART_LLM=claude-sonnet-4-6을 설정해도 Claude id가 여러분의 base URL을 통해 라우팅되지 않습니다; 대신 gpt-researcher가 그 문자열을 다른 프로바이더로 해석하려 듭니다. 커스텀 엔드포인트를 향하는 모든 모델은 openai: 접두어를 유지해야 합니다. 여기서 "openai"는 벤더가 아니라 프로토콜의 이름이기 때문입니다. 오버라이드를 조용히 따라가는 임베딩. 기본 EMBEDDING은 OpenAI 형태의 모델이므로, OPENAI_BASE_URL이 게이트웨이를 가리키면 임베딩 요청도 그리로 갑니다. 게이트웨이가 그 임베딩 id를 서빙하지 않으면, 리서치 실행은 첫 채팅 호출이 아니라 소스 처리 중에 실패하는데, 이는 사람들이 엉뚱한 슬롯을 디버깅하게 만듭니다. EMBEDDING을 명시적으로 설정하면 이 증상이 사라집니다. 리트리버 실패를 엔드포인트 탓으로 돌리는 경우. TAVILY_API_KEY가 없거나 소진되면 검색 단계가 깨지고, 그 결과 나오는 빈 소스 오류는 표면적으로 LLM 실패처럼 보입니다. 리트리버는 별도의 키를 가진 별도의 서비스이니 따로 확인하세요. 실행 간 오래된 환경. .env 파일은 작업 디렉터리에서 읽힙니다. 웹 앱은 한 디렉터리에서, Python API는 다른 디렉터리에서 실행하면 서로 다른 설정 두 개가 되며, "앱에서는 되는데 제 스크립트에서는 안 돼요"는 거의 항상 이것입니다. 토큰 한도 설정은 모델 능력과 별개입니다. gpt-researcher는 보수적인 기본값을 가진 자체 슬롯별 토큰 한도(FAST_TOKEN_LIMIT, SMART_TOKEN_LIMIT 및 관련 설정)를 가지고 있습니다. SMART_LLM을 롱컨텍스트 모델로 지정한다고 해서 그 한도가 저절로 올라가지는 않습니다; 더 긴 생성을 원한다면 의도적으로 조정하세요.

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

• 단일 벤더 관계보다 세 모델 슬롯에 걸친 실행당 비용 가시성이 더 중요한, 반복 보고서(시장 스캔, 문헌 리뷰, 경쟁 브리핑)를 생성하는 팀.
• 작가 모델을 비교하는 연구자. FAST와 STRATEGIC은 고정한 채 SMART를 Claude, GPT, DeepSeek id 사이에서 바꾸는 것은 벤더 계정 세 개가 아니라 .env 편집 세 번입니다.
• 제품에 gpt-researcher를 내장하는 빌더 — 배포 파이프라인의 벤더 시크릿 묶음 대신 환경당 게이트웨이 키 하나.
• gpt-researcher의 기본 OpenAI 형태 설정을 건드리지 않으면서 보고서 작성을 Claude나 Gemini가 하길 원하는 사용자.
• 특정 벤더의 결제 수단에 접근할 수 없는 개발자. 카드 없이 충전만으로 사용할 수 있어 프로바이더별 가입 의존성이 사라집니다.

엔드포인트 검증 및 첫 보고서 디버깅.

먼저 게이트웨이의 모델을 나열하세요; 각 슬롯에서 openai: 뒤의 문자열은 버전 접미사까지 포함해 서빙되는 id와 정확히 일치해야 합니다. 첫 실행 실패는 깔끔하게 정리됩니다. 401은 프로세스가 실제로 보는 환경에 OPENAI_API_KEY가 없다는 뜻입니다; .env 파일은 작업 디렉터리에서 로드되므로, 파일이 있는 곳에서 실행하거나 변수를 전역으로 export하세요. model-not-found 오류는 오타가 있는 슬롯을 지목합니다. 계획 단계가 아니라 소스 처리 중의 실패는 채팅 슬롯이 아니라 임베딩이나 리트리버를 가리킵니다: LLM 설정을 건드리기 전에 EMBEDDING과 TAVILY_API_KEY를 확인하세요. 전체 리서치 실행은 세 슬롯 모두에 걸친 수십 번의 요청이 몰아치므로, 완료되면 APIsRouter 콘솔의 요청별 뷰가 실제 토큰과 실제 지출로 FAST/SMART/STRATEGIC 분할을 보는 가장 빠른 방법이며, 자기 역할보다 더 많이 소비하는 슬롯을 잡아내는 방법이기도 합니다.

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

자주 묻는 질문