agentjido/req_llm

ReqLLM이란 무엇인가요?

ReqLLM은 단일하고 일관된 API를 통해 많은 대규모 언어 모델(LLM) 제공업체(OpenAI, Anthropic, Azure, Google Gemini 등)와 통신할 수 있게 해주는 오픈 소스 Elixir 라이브러리입니다. 인기 있는 Req HTTP 클라이언트와 Finch 스트리밍 라이브러리를 기반으로 구축되어, 각 제공업체의 특이한 사항들을 처리하므로 어떤 모델을 사용하든 동일한 Elixir 코드를 작성할 수 있습니다.

왜 중요한가요?

제공업체에 독립적 – 21개 이상의 제공업체로부터 온 1,200개 이상의 모델이 라이브러리의 모델 카탈로그에 등록되어 있습니다. "anthropic:claude-haiku-4-5"와 같은 문자열로 모델을 선택하면 라이브러리가 해당 제공업체에 맞는 HTTP 형태로 요청을 변환합니다.
통합된 고수준 헬퍼 – generate_text/3, stream_text/3, generate_object/4와 같은 함수는 Vercel AI SDK 스타일을 모방하여, 동일한 호출 시그니처로 일반 텍스트, 구조화된 JSON 또는 이미지까지 생성할 수 있습니다.
스트리밍 지원 – Finch를 통해 제공업체 전반에서 실시간 토큰 스트리밍이 작동하며, 사용량 메타데이터를 수집하면서 토큰을 생성하는 StreamResponse를 제공합니다.
구조화된 출력 및 도구 호출 – 기대하는 결과의 형태(객체, 배열, JSON 스키마 등)를 설명할 수 있으며, 라이브러리가 제공업체의 응답을 검증하여 함수 호출 워크플로우를 더 쉽게 만들어줍니다.
비용 및 사용량 추적 – 모든 응답에는 토큰 수와 최선의 USD 비용 추정치가 포함되며, OpenTelemetry 또는 기타 관측 스택에 연결할 수 있는 텔레메트리 이벤트도 제공됩니다.

핵심 개념 (빠른 요약)

개념	설명	일반적인 용도
Model spec	제공업체와 모델 ID를 식별하는 문자열, 튜플 또는 `%LLMDB.Model{}` (예: `"openai:gpt-4o"`).	호출할 모델 선택.
Context	`ReqLLM.Context.*`로 구축된 시스템/사용자/어시스턴트 메시지 목록.	멀티턴 대화 기록 제공.
Output descriptor	기대하는 형태(텍스트, 객체, 배열, JSON 스키마 등)를 선언하는 `ReqLLM.Output` 구조체.	모델에 구조화된 데이터 반환 요청.
Response structs	`ReqLLM.Response`, `ReqLLM.StreamResponse`, `ReqLLM.Usage`.	생성된 텍스트, 이미지, 임베딩, 사용량 및 비용 확인.
Provider transports	내부적으로 Req가 HTTP 요청을 구축하고, Finch가 스트리밍을 처리합니다.	Req 또는 Finch를 직접 호출할 필요가 없습니다.
Key management	`ReqLLM.Keys`가 환경 변수, `.env` 파일 또는 인메모리 저장소에서 API 키를 가져옵니다.	인증 정보를 코드에서 분리합니다.

시작하기 (최단 경로)

# Igniter를 통해 라이브러리 추가 (권장)
mix igniter.install req_llm

# 코드 내에서
model = "anthropic:claude-haiku-4-5"

# 단순 원샷 텍스트 생성
text = ReqLLM.generate_text!(model, "Hello world")
# => "Hello! How can I assist you today?"

# 구조화된 객체 생성
schema = [name: [type: :string, required: true], age: [type: :pos_integer]]
person = ReqLLM.generate_object!(model, "Generate a person", schema)
# => %{name: "John Doe", age: 30}

스트리밍의 경우:

{:ok, resp} = ReqLLM.stream_text(model, "Write a short story")
ReqLLM.StreamResponse.tokens(resp) |> Stream.each(&IO.write/1) |> Stream.run()

더 자세히 살펴볼 가치가 있는 주요 기능

제공업체별 옵션 – 예: provider_options: [web_search: %{max_uses: 5}]는 Anthropic의 웹 검색 도구를 활성화합니다.
임베딩 생성 – 제공업체가 지원하는 경우 Embedding.generate/3가 단일 또는 배치 임베딩을 반환합니다.
OpenAI 실시간 세션 – 최신 실시간 모델을 위한 저수준 WebSocket API (ReqLLM.OpenAI.Realtime).
Telemetry – 내장된 Telemetry 이벤트 ([:req_llm, :request, …], [:req_llm, :token_usage]) 및 전체 트레이싱을 위한 선택적 OpenTelemetry 연결.
확장 가능한 모델 레지스트리 – 전체 스펙 맵을 전달하고 ReqLLM.model!/1로 정규화함으로써 카탈로그에 아직 없는 모델을 호출할 수 있습니다.

누가 사용해야 하나요?

Elixir 개발자 – 챗봇, 에이전트 또는 모든 GenAI 기반 서비스를 구축하며, 수십 개의 제공업체 SDK를 다루는 대신 단일하고 관용적인 클라이언트를 원하는 개발자.
팀 – 기본적으로 비용 가시성 및 구조화된 출력 검증이 필요한 팀.
Ops / 관측 담당자 – 청구 대시보드용으로 준비된 Telemetry 훅을 원하는 담당자.

더 배우기

Hex 패키지 페이지 – https://hex.pm/packages/req_llm
전체 문서 – https://hexdocs.pm/req_llm/
제공업체 가이드 – 리포지토리의 guides/ 참조 (예: guides/openai.md).
Discord 커뮤니티 – https://jido.run/discord (The Swarm: Elixir AI Collective).

요약 (TL;DR)

ReqLLM은 단일 Elixir API를 통해 수백 개의 LLM 모델(텍스트, 임베딩, 이미지, 음성, OCR 등)을 호출할 수 있게 해주며, 스트리밍, 구조화된 출력, 비용 추적 및 Telemetry가 내장되어 있습니다. 각 제공업체의 특이성을 추상화하여 프롬프트와 필요한 데이터에 집중할 수 있게 합니다.