코드 한 줄로 로컬로: 기본 주소 설정 읽는 법
2026-10-09 마지막 수정
「로컬로도 돌릴 수 있다」는 말은 README 보다 코드 한 줄이 더 정확하게 알려 줍니다. 클라우드 API 를 부르는 코드가 그 주소를 설정에서 읽고, 그 설정을 로컬 서버로 바꿀 수 있으면 그 호출은 내 컴퓨터 안에서 끝납니다. 이 글은 그 한 줄이 실제로 어떻게 생겼는지, 로컬 서버로 바꿀 때 무엇을 넣는지, 결과 페이지에서 어떻게 찾는지 설명합니다.
OpenAI 호환 주소라는 관례
Ollama, LM Studio, llama.cpp 서버, vLLM 같은 로컬 실행기는 대부분 OpenAI API 와 같은 모양의 주소(/v1/chat/completions 등)를 엽니다. 그래서 OpenAI SDK 로 짠 코드라도 요청을 보낼 기본 주소(base URL)만 바꾸면 로컬 모델에 그대로 붙습니다. 이 사이트가 「로컬 주소로 바꾸는 설정」이라고 부르는 것이 이 기본 주소를 정하는 설정입니다.
공급자별로 이런 설정이 있는 저장소가 얼마나 되는지는 API별 저장소의 「로컬로 바꾸는 설정」 칸에 지금 숫자로 나옵니다.
코드에서 본 두 가지 모양
1. 환경 변수를 읽고, 없으면 로컬 기본값
TauricResearch/TradingAgents 의 cli/prompts.py 361번째 줄은 OLLAMA_BASE_URL 환경 변수를 읽고, 비어 있으면 http://localhost:11434/v1 을 씁니다. 바로 아래 공급자 목록에는 OpenAI·Anthropic 같은 클라우드 주소와 이 Ollama 주소가 나란히 있습니다. 같은 저장소의 docker-compose.yml 24번째 줄도 같은 변수를 http://ollama:11434/v1 로 채웁니다.
이런 코드는 「클라우드를 고를 수도 있고 로컬을 고를 수도 있다」는 뜻입니다. 결과 페이지에서는 저장소 상태가 「외부 API 사용 · 로컬 대안 있음」이 되고, 기능 표의 대체 경로 칸에 로컬 실행기가 나옵니다.
2. 클라이언트를 만들 때 주소를 설정에서 받기
Tencent/WeKnora 의 dataset/qa_dataset.py 122번째 줄은 OpenAI 클라이언트를 만들면서 키는 OPENAI_API_KEY, 주소는 OPENAI_BASE_URL 에서 받습니다. 기본값은 코드에 없어서, 아무것도 넣지 않으면 SDK 의 기본 주소(OpenAI)로 갑니다. 대신 이 변수에 로컬 서버 주소를 넣으면 같은 코드가 로컬 모델을 부릅니다.
첫 번째 모양과 다른 점은 기본값이 어디냐입니다. 첫 번째는 비워 두면 로컬, 두 번째는 비워 두면 클라우드입니다. 결과 페이지는 이 차이를 「기본값 클라우드」 꼬리표와 「로컬 주소로 변경 가능」 꼬리표로 나눠 적습니다.
로컬 서버로 바꿀 때 넣는 값
설정 이름은 저장소마다 다르지만(OPENAI_BASE_URL, OLLAMA_BASE_URL, base_url, api_base 등), 넣는 값은 세 가지입니다.
- 주소: 로컬 실행기가 여는 OpenAI 호환 주소. 기본 설정 그대로 띄웠다면 대개 아래와 같습니다.
- 키: 로컬 서버는 키를 확인하지 않지만, OpenAI SDK 는 키가 비어 있으면 요청 전에 오류를 냅니다. 이럴 때는
local같은 아무 문자열이나 넣습니다. - 모델 이름: 클라우드 모델 이름(
gpt-…)이 아니라 로컬에 받아 둔 모델의 이름을 넣어야 합니다. Ollama 라면ollama list에 나오는 이름입니다.
| 로컬 실행기 | 기본 주소 |
|---|---|
| Ollama | http://localhost:11434/v1 |
| LM Studio | http://localhost:1234/v1 |
llama.cpp (llama-server) | http://localhost:8080/v1 |
| vLLM | http://localhost:8000/v1 |
포트를 바꿔 띄웠거나 다른 컴퓨터에서 돌린다면 그 주소로 바꿉니다. 도커 안에서 도는 도구라면 localhost 가 컨테이너 자신을 가리키므로, 위 TradingAgents 의 docker-compose.yml 처럼 서비스 이름(http://ollama:11434/v1)이나 호스트 주소를 써야 합니다.
결과 페이지에서 찾는 법
- 저장소 상태가 「외부 API 사용 · 로컬 대안 있음」이면 적어도 한 호출에 로컬로 가는 길이 코드에 있습니다.
- 기능 표의 「기본 설정」 칸은 비워 둘 때 어디로 가는지, 「대체 경로」 칸은 바꿀 수 있는 곳을 보여 줍니다.
- 호출 위치를 펼치면 커밋에 고정된 파일과 줄 번호로 바로 갑니다. 위 두 예시의 링크도 그 위치입니다.
이 설정이 말해 주지 않는 것
주소를 바꿀 수 있다는 것과 로컬 모델로 똑같이 잘 돈다는 것은 다른 이야기입니다. 도구가 특정 모델의 기능(긴 문맥, 도구 호출 형식 등)에 기대고 있으면 로컬 모델에서 결과가 달라질 수 있습니다. 또 한 저장소 안에서도 어떤 호출은 바꿀 수 있고 어떤 호출은 고정된 클라우드 주소일 수 있습니다. 그래서 이 사이트는 저장소 전체를 한 문장으로 묶지 않고, 호출마다 따로 적습니다.