> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crazyrouter.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LangChain 설정 가이드

> LangChain의 Python 및 JavaScript / TypeScript 프로젝트에서 OpenAI 호환 방식으로 Crazyrouter를 연동하고, 설치, 환경 변수, 검증, RAG, 문제 해결 절차까지 안내합니다

> 업데이트: 2026-06-06

LangChain은 가장 널리 쓰이는 LLM 애플리케이션 개발 프레임워크 중 하나로, 채팅 인터페이스 래핑, 프롬프트 체인, 도구 호출, RAG, 에이전트형 워크플로, 애플리케이션 수준 오케스트레이션에 적합합니다. Crazyrouter를 연동할 때 가장 안정적인 방법은 LangChain이 공식 지원하는 OpenAI 호환 컴포넌트를 사용하는 것입니다.

## 개요

LangChain의 OpenAI 컴포넌트를 통해 요청을 Crazyrouter로 보낼 수 있습니다.

* 권장 프로토콜: `OpenAI-compatible API`
* Base URL: `https://api.crazyrouter.com/v1`
* 인증 변수: `OPENAI_API_KEY`
* Python 메인 패키지: `langchain-openai`
* JavaScript / TypeScript 메인 패키지: `@langchain/openai`

<Tip>
  데스크톱 클라이언트에서 채팅만 하는 것이 아니라 Crazyrouter를 자체 애플리케이션 코드에 통합하려는 경우, LangChain은 대체로 가장 자연스러운 엔지니어링 연동 경로입니다.
</Tip>

## 이런 분들께 적합합니다

* Python 또는 Node.js 프로젝트에 Crazyrouter를 정식으로 통합하려는 개발자
* 프롬프트 체인, RAG, 도구 호출, 워크플로 오케스트레이션을 하려는 분
* 모델 호출 로직을 통일된 형태로 추상화하고, 저수준 HTTP 요청을 직접 작성하고 싶지 않은 분
* 이후 모델이나 업스트림을 유연하게 전환할 수 있는 여지를 남기고 싶은 분

## 사용 프로토콜

권장 프로토콜: `OpenAI-compatible API`

Crazyrouter에 대응하는 핵심 설정:

```text theme={null}
OPENAI_API_KEY=sk-xxx
BASE_URL=https://api.crazyrouter.com/v1
```

LangChain에서의 일반적인 대응 표기는 다음과 같습니다.

* Python: `api_key` + `base_url`
* JavaScript / TypeScript: `apiKey` + `configuration.baseURL`

## 시스템 요구 사항과 사전 조건

| 항목             | 설명                                                       |
| -------------- | -------------------------------------------------------- |
| Crazyrouter 계정 | 먼저 [crazyrouter.com](https://crazyrouter.com)에서 가입       |
| Crazyrouter 토큰 | LangChain 프로젝트 전용 토큰을 별도로 생성하는 것을 권장                     |
| Python         | `Python 3.10+` 권장                                        |
| Node.js        | `Node.js 18+` 권장                                         |
| LangChain 패키지  | Python은 `langchain-openai`; JS / TS는 `@langchain/openai` |
| 사용 가능 모델       | 최소 채팅 모델 1개 허용; 벡터 검색을 하려면 embedding 모델도 허용 필요           |

권장 초기 화이트리스트:

* `gpt-5.5`
* `claude-opus-4-8`
* `gemini-3.1-pro`
* `text-embedding-3-large`

## Python 프로젝트 전체 연동 경로

### Windows 권장 경로

```powershell theme={null}
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
pip install -U langchain-openai langchain-community
python --version
pip --version
```

FAISS 예제를 실행하려면 추가로:

```powershell theme={null}
pip install faiss-cpu
```

### macOS / Linux 권장 경로

```bash theme={null}
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install -U langchain-openai langchain-community
python --version
pip --version
```

FAISS 예제를 실행하려면 추가로:

```bash theme={null}
pip install faiss-cpu
```

## JavaScript / TypeScript 프로젝트 전체 연동 경로

### Windows PowerShell

```powershell theme={null}
npm init -y
npm install @langchain/openai @langchain/core
node -v
npm -v
```

### macOS / Linux

```bash theme={null}
npm init -y
npm install @langchain/openai @langchain/core
node -v
npm -v
```

## 처음부터 전체 설정하기

<Steps>
  <Step title="1단계: Crazyrouter에서 LangChain 전용 토큰 생성">
    처음에는 다음만 허용하는 것을 권장합니다.

    * `gpt-5.5`
    * `claude-opus-4-8`
    * `text-embedding-3-large`

    이후 더 많은 모델이 필요하면 필요에 따라 확장하되, 처음에는 최소 화이트리스트를 유지하세요.
  </Step>

  <Step title="2단계: 먼저 환경 변수 설정">
    <Tabs>
      <Tab title="macOS / Linux">
        ```bash theme={null}
        export OPENAI_API_KEY=sk-xxx
        echo $OPENAI_API_KEY
        ```
      </Tab>

      <Tab title="Windows PowerShell">
        ```powershell theme={null}
        $env:OPENAI_API_KEY = "sk-xxx"
        echo $env:OPENAI_API_KEY
        ```
      </Tab>
    </Tabs>

    장기적으로 개발할 계획이라면 영속화도 함께 진행하세요.

    <Tabs>
      <Tab title="Linux Bash">
        ```bash theme={null}
        echo 'export OPENAI_API_KEY=sk-xxx' >> ~/.bashrc
        source ~/.bashrc
        ```
      </Tab>

      <Tab title="macOS / Zsh">
        ```bash theme={null}
        echo 'export OPENAI_API_KEY=sk-xxx' >> ~/.zshrc
        source ~/.zshrc
        ```
      </Tab>

      <Tab title="Windows PowerShell">
        ```powershell theme={null}
        [System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-xxx", "User")
        $env:OPENAI_API_KEY = "sk-xxx"
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="3단계: Python 최소 채팅 검증 완료">
    `test_langchain_chat.py`를 새로 만듭니다.

    ```python theme={null}
    from langchain_openai import ChatOpenAI

    llm = ChatOpenAI(
        model="gpt-5.5",
        api_key="sk-xxx",
        base_url="https://api.crazyrouter.com/v1",
        temperature=0,
    )

    response = llm.invoke("Reply only OK")
    print(response.content)
    ```

    실행:

    ```bash theme={null}
    python test_langchain_chat.py
    ```
  </Step>

  <Step title="4단계: 환경 변수 버전으로 변경">
    실행이 확인되면, key를 코드에 하드코딩하지 않는 것을 권장합니다.

    ```python theme={null}
    import os
    from langchain_openai import ChatOpenAI

    llm = ChatOpenAI(
        model="gpt-5.5",
        api_key=os.environ["OPENAI_API_KEY"],
        base_url="https://api.crazyrouter.com/v1",
        temperature=0,
    )
    ```
  </Step>

  <Step title="5단계: JavaScript / TypeScript 최소 채팅 검증 완료">
    `test-langchain-chat.mjs`를 새로 만듭니다.

    ```javascript theme={null}
    import { ChatOpenAI } from "@langchain/openai";

    const llm = new ChatOpenAI({
      model: "gpt-5.5",
      apiKey: process.env.OPENAI_API_KEY,
      configuration: {
        baseURL: "https://api.crazyrouter.com/v1",
      },
      temperature: 0,
    });

    const response = await llm.invoke("Reply only OK");
    console.log(response.content);
    ```

    실행:

    ```bash theme={null}
    node test-langchain-chat.mjs
    ```
  </Step>

  <Step title="6단계: Embeddings, Prompt, RAG를 단계적으로 추가">
    처음부터 복잡한 체인을 바로 도입하는 것은 권장하지 않습니다. 권장 순서:

    1. 먼저 단일 턴 채팅을 성공시키기
    2. 다음으로 Prompt + Output Parser 실행
    3. 그다음 Embeddings 연동
    4. 마지막으로 RAG 또는 Agent 구성
  </Step>
</Steps>

## Python 예제

### 최소 채팅 예제

```python theme={null}
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-5.5",
    api_key="sk-xxx",
    base_url="https://api.crazyrouter.com/v1",
    temperature=0.7,
)

response = llm.invoke("LangChain이란 무엇인가요?")
print(response.content)
```

### Embeddings 예제

```python theme={null}
from langchain_openai import OpenAIEmbeddings

embeddings = OpenAIEmbeddings(
    model="text-embedding-3-large",
    api_key="sk-xxx",
    base_url="https://api.crazyrouter.com/v1",
)

vectors = embeddings.embed_documents(["텍스트 하나", "텍스트 둘"])
print(len(vectors), len(vectors[0]))
```

### Prompt 체인 예제

```python theme={null}
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

llm = ChatOpenAI(
    model="gpt-5.5",
    api_key="sk-xxx",
    base_url="https://api.crazyrouter.com/v1",
)

prompt = ChatPromptTemplate.from_template("간단한 언어로 {topic}을(를) 설명해 주세요")
chain = prompt | llm | StrOutputParser()

result = chain.invoke({"topic": "양자 컴퓨팅"})
print(result)
```

### RAG 최소 예제

```python theme={null}
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
from langchain_community.vectorstores import FAISS
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough

llm = ChatOpenAI(
    model="gpt-5.5",
    api_key="sk-xxx",
    base_url="https://api.crazyrouter.com/v1",
)

embeddings = OpenAIEmbeddings(
    model="text-embedding-3-large",
    api_key="sk-xxx",
    base_url="https://api.crazyrouter.com/v1",
)

texts = [
    "Crazyrouter는 다양한 AI 모델 프로토콜을 지원합니다",
    "Crazyrouter는 OpenAI 호환 호출 방식을 지원합니다",
]

vectorstore = FAISS.from_texts(texts, embeddings)
retriever = vectorstore.as_retriever()

prompt = ChatPromptTemplate.from_template(
    "다음 컨텍스트를 바탕으로 질문에 답하세요:\n{context}\n\n질문: {question}"
)

chain = {"context": retriever, "question": RunnablePassthrough()} | prompt | llm

result = chain.invoke("Crazyrouter는 LangChain을 연동할 때 어떤 프로토콜이 적합한가요?")
print(result.content)
```

## JavaScript / TypeScript 예제

### 최소 채팅 예제

```javascript theme={null}
import { ChatOpenAI } from "@langchain/openai";

const llm = new ChatOpenAI({
  model: "gpt-5.5",
  apiKey: process.env.OPENAI_API_KEY,
  configuration: {
    baseURL: "https://api.crazyrouter.com/v1",
  },
  temperature: 0,
});

const response = await llm.invoke("안녕하세요");
console.log(response.content);
```

## 권장 모델 구성

| 사용 시나리오         | 권장 모델                    | 이유                                                                          |
| --------------- | ------------------------ | --------------------------------------------------------------------------- |
| 첫 번째 연결 검증      | `gpt-5.5`                | 2026년 3월 23일 프로덕션 환경에서 실측 성공, LangChain과 Crazyrouter가 연결되었는지 먼저 확인하기에 가장 적합 |
| 고품질 장문 및 복잡한 체인 | `claude-opus-4-8`        | 복잡한 설명, 요약, 무거운 추론 작업에 적합                                                   |
| Gemini 대체 옵션    | `gemini-3.1-pro`         | 두 번째 호환성 검증 경로로 적합                                                          |
| 벡터 검색           | `text-embedding-3-large` | embedding 기준선 검증에 적합                                                        |

## 토큰 설정 모범 사례

| 설정        | 권장    | 설명                                         |
| --------- | ----- | ------------------------------------------ |
| 전용 토큰     | 필수    | LangChain 프로젝트는 데스크톱 클라이언트와 토큰을 공유하지 않아야 함 |
| 모델 화이트리스트 | 강력 권장 | 먼저 채팅 모델 + embedding 모델만 허용                |
| 할당량 상한    | 강력 권장 | 체인 호출, RAG, Agent는 소비를 증폭시킴                |
| 환경 격리     | 권장    | dev / staging / production 토큰을 분리          |
| 유출 대응     | 즉시 교체 | key를 Git에 커밋하지 말 것; 유출 시 즉시 교체             |

## 검증 체크리스트

* [ ] Python 또는 Node.js 실행 환경 준비 완료
* [ ] `OPENAI_API_KEY`가 올바르게 설정됨
* [ ] `langchain-openai` 또는 `@langchain/openai`가 설치됨
* [ ] 채팅 모델의 `base_url` / `baseURL`이 `https://api.crazyrouter.com/v1`로 설정됨
* [ ] 첫 번째 `Reply only OK` 요청이 성공적으로 반환됨
* [ ] Crazyrouter 백엔드 로그에서 해당 요청이 확인됨
* [ ] embeddings를 사용하는 경우, embedding 모델도 허용되어 있음
* [ ] RAG를 사용하는 경우, 먼저 최소 텍스트 집합에서 검증을 완료함

## 자주 발생하는 오류와 해결 방법

| 증상                | 일반적인 원인                                   | 해결 방법                                |
| ----------------- | ----------------------------------------- | ------------------------------------ |
| 401 unauthorized  | `OPENAI_API_KEY`가 잘못되었거나 만료되었거나 복사 오류     | 토큰을 재생성하고 환경 변수를 다시 설정               |
| 404               | `base_url` / `baseURL`이 잘못되었거나 `/v1`이 누락됨 | `https://api.crazyrouter.com/v1`로 수정 |
| `model not found` | 모델명 오타 또는 토큰에 허용되지 않음                     | `gpt-5.5` 등 확인된 모델로 되돌리고 화이트리스트 확인   |
| embeddings 오류     | embedding 모델 허용을 잊음                       | 토큰에 `text-embedding-3-large` 추가      |
| RAG가 동작하지 않음      | 처음부터 너무 많은 컴포넌트를 연결함                      | 단일 턴 채팅으로 되돌린 후 단계적으로 추가             |
| 소비량이 너무 빠름        | 체인 호출, 검색, 다중 턴 Agent가 누적됨                | 체인을 축소하고 토큰 할당량을 별도로 제어              |

## FAQ

### LangChain에서 Crazyrouter를 연동할 때 어떤 프로토콜을 사용해야 하나요?

OpenAI 호환 프로토콜을 우선적으로 사용하세요.

### Base URL은 무엇을 입력해야 하나요?

`https://api.crazyrouter.com/v1`을 입력하세요.

### Python에서는 어떤 패키지를 사용해야 하나요?

`langchain-openai`를 우선적으로 사용하세요.

### JavaScript / TypeScript에서는 어떤 패키지를 사용해야 하나요?

`@langchain/openai`를 우선적으로 사용하세요.

### 처음에 Agent나 대규모 RAG를 바로 도입하지 않는 것이 좋은 이유는 무엇인가요?

LangChain 체인이 일단 복잡해지면 문제 해결 비용이 크게 증가하기 때문입니다. 먼저 최소 채팅을 성공시킨 후 단계적으로 컴포넌트를 추가하는 것이 가장 안정적입니다.

<Note>
  Crazyrouter를 자체 애플리케이션 프로젝트에 정식으로 연동하려는 경우, LangChain은 여전히 가장 우선적으로 갖춰야 할 개발 프레임워크 문서 중 하나입니다.
</Note>