Go AI 클라이언트 라이브러리
CI
License: MIT
Go Version
마이그레이션 중인가요? MIGRATION.md에는 두 가지 전환 사항이 포함되어 있습니다: v0.18.x → v0.1.0 (단일 모듈이 약 50개의 공급자별 모듈로 분할됨) 및 v0.1.x → v0.2.0 (memory와 session이 agent/에서 최상위 모듈로 분리됨).
LLM, 임베딩(embeddings), 이미지 생성, TTS, STT, 리랭커(rerankers), 그리고 fill-in-the-middle을 위한 다중 공급자 Go 라이브러리입니다. 각 기능은 하나의 양식(modality) 모듈이며, 각 공급자 구현체는 자체 서브모듈이므로 실제로 사용하는 SDK만 가져오면 됩니다.
문서화
주요 기능 (Features)
- 공급자별 모듈(Per-vendor modules) — 필요한 SDK만 가져와서 불필요한 종속성 증가를 방지합니다.
- LLM — 채팅, 스트리밍(streaming), 툴 호출(tool calling), 구조화된 출력(structured output), 추론(reasoning)
- Agent 프레임워크 — 서브 에이전트(Sub-agents), 핸드오프(handoffs), 팬아웃(fan-out), 세션(sessions), 영구 메모리(persistent memory), 컨텍스트 전략
- 음성 에이전트(Voice agent) — 바지인(barge-in), 필러 오디오(filler audio), 툴 호출 사운드, 세션, 후크(hooks), 핸드오프, 툴셋, 메모리를 갖춘 저지연 스트리밍 STT → LLM → TTS 파이프라인
- 임베딩(Embeddings) — 텍스트, 멀티모달, 컨텍스트화된 임베딩 지원
- 이미지 생성 — OpenAI, Gemini, xAI
- 오디오(Audio) — TTS (ElevenLabs, OpenAI, Google Cloud, Azure Speech) 및 STT (OpenAI Whisper, ElevenLabs Scribe, Deepgram, AssemblyAI, Google Cloud)
- 리랭커(Rerankers) — Voyage AI, Cohere
- 의사 결정 모델(Decision models) — TypeSafe Jev (System One): 텍스트 생성 없이 타입이 지정된 선택지, 점수 및 예/아니오 답변 지원
- fill-in-the-middle — Mistral, DeepSeek
- 배치 처리(Batch processing) — 네이티브 배치 API (OpenAI, Anthropic, Gemini) 또는 모든 공급자를 위한 경계가 지정된 동시성(bounded concurrency)
- MCP 통합 — Model Context Protocol 도구링
- OpenTelemetry 트레이싱 — 모든 공급자 호출에 걸친 GenAI 의미론적 컨벤션 지원
- 비용 추적(Cost tracking) — 토큰/문자 사용량 및 비용 계산 기능
모듈 구조 (Module structure)
이 라이브러리는 계층별로 구성된 약 50개의 독립적인 Go 모듈로 게시됩니다:
- Tier 0 라이브러리(leaves) —
model, message, tool, schema, tracing, prompt, types (벤더 SDK 미포함)
- Tier 1 모달리티 인터페이스 —
llm, embeddings, tts, stt, image, rerankers, fim, decision (벤더 SDK 미포함)
- Tier 2 벤더 구현체 —
llm/openai, llm/anthropic, embeddings/voyage, tts/elevenlabs 등 (벤더 SDK 포함)
- Tier 3 유틸리티 —
tokens/{sliding,truncate,summarize}, batch/{openai,anthropic,gemini,concurrent}
- Tier 4 에이전트 런타임 —
agent, agent/team, session, memory, voice
- Tier 5 영속성(Persistence) —
memory/{pgvector,postgres,sqlite}
모든 패키지, 그 목적 및 포함된 벤더 SDK는 **전체 모듈 목록**을 참조하십시오.
설치(Installation)
사용하는 모듈만 설치하면 됩니다. OpenAI 채팅 클라이언트의 경우:
go get github.com/joakimcarlsson/ai/llm
go get github.com/joakimcarlsson/ai/llm/openai
go get github.com/joakimcarlsson/ai/message
빠른 시작(Quick start)
package main
import (
...
)
지원되는 제공업체(Supported providers)
| 제공업체 | LLM | 임베딩(Embeddings) | 이미지 | TTS | STT | 리랭커(Rerankers) | FIM | 결정(Decision) |
|---|
| OpenAI | ✅ | ✅ | ✅ | ✅ | ✅ | | | |
| ... | | | | | | | | |
BYOM을 통해 모든 OpenAI 호환 엔드포인트를 추가할 수 있습니다.
에이전트 프레임워크(Agent framework)
import (
"github.com/joakimcarlsson/ai/agent"
"github.com/joakimcarlsson/ai/session"
...
)
에이전트 프레임워크는 sub-agents, handoffs, fan-out, team coordination, continue/resume, context strategies, persistent memory, 그리고 instruction templates를 지원합니다.
음성 에이전트 (Voice agent)
voice/는 저지연(low-latency), 음성 우선형 대화 에이전트를 구축하기 위한 스트리밍 STT (SpeechToText) → LLM (Large Language Model) → TTS (TextToSpeech) 파이프라인을 제공합니다. 플러그인 가능한 프로바이더를 통해 임의의 stt.SpeechToText, llm.LLM, 및 tts.Generation 구현체를 사용할 수 있습니다.
import (
"github.com/joakimcarlsson/ai/session"
"github.com/joakimcarlsson/ai/voice"
...
음성 에이전트는 [barge-in], [filler audio] 및 느린 첫 토큰/도구 실행을 위한 [tool-call sounds], [sessions], [context strategies], [hooks], [handoffs], [toolsets], 그리고 [memory]를 지원합니다. examples/voice/ 아래에 네 가지 실행 가능한 엔드투엔드 예제(web (kitchen-sink), handoff, toolsets, memory)가 있습니다.
배치 처리 (Batch processing)
각 배치 백엔드는 자체 모듈입니다. 네이티브 배치 API는 단일 비동기 작업(async job)을 제출하며, 동시 실행기(concurrent runner)는 제한된 동시성(bounded concurrency)으로 기존 클라이언트를 감싸 사용합니다.
import (
"github.com/joakimcarlsson/ai/batch"
batchopenai "github.com/joakimcarlsson/ai/batch/openai"
...
개별 항목 오류 처리(Per-item error handling), 진행률 콜백(progress callbacks), 비동기 채널 기반 추적(async channel-based tracking)이 모두 지원됩니다. 배치 처리 문서를 참조하세요.
작업 공간 설정 (Workspace setup)
이 저장소는 루트 모듈이 없는 순수 Go 작업 공간(pure Go workspace)입니다. 로컬에서 작업하려면 다음을 따르세요:
git clone https://github.com/joakimcarlsson/ai
cd ai
cp go.work.example go.work
...
go.work.example은 git에 커밋된 표준 작업 공간 파일이며, 기여자들은 이를 복사하거나 go.work로 심볼릭 링크합니다.
버전 관리 (Versioning)
각 모듈은 경로 접두사(path-prefixed)가 지정된 git 태그를 사용하여 독립적으로 버전 관리됩니다. 이 태그 접두사는 하위 디렉터리 경로와 정확히 일치해야 합니다. 이는 Go 모듈 시스템이 버전을 해결하는 방식입니다.
릴리스 프로세스 (Release process)
릴리스는 AWS SDK v2 패턴을 따릅니다. main 브랜치에서의 CI가 안전망(safety net) 역할을 하며, git 태그가 go get 해결을 유도하고, 날짜가 지정된 GitHub Releases에서 변경 로그를 제공합니다.
1. main 브랜치가 성공했는지 확인하기 (Ensure main is green)
태그를 붙이기 전에 CI는 최신 커밋에 대해 통과해야 합니다.
2. 변경된 모듈 태그 지정하기 (Tag modules that changed)
scripts/release.sh modules
...
이 스크립트는 해당 모듈의 go.mod가 존재하는지, 그리고 태그 접두사가 디렉터리 경로와 일치하는지 확인합니다.
3. 직접 소비자에게 전파하기 (공유 모듈 버전 올리기 시) (Cascade to direct consumers (when bumping a shared module))
변경된 모듈이 사용자에게 노출되는 심볼(user-facing symbols)을 제공하는 공유 종속성(shared dep)인 경우, 브랜치를 열고 일반 사용자가 새로운 심볼에 접근하기 위해 go get 하는 모든 모듈의 require 라인을 증가시켜야 합니다. 예를 들어, 새로운 Gemini 상수를 추가하는 model 변경은 llm/gemini, image/gemini, embeddings/gemini, batch/gemini, 그리고 llm/vertexai에 연쇄적으로(cascades) 영향을 미치지만, 관련 없는 제공업체(llm/openai, llm/anthropic)나 사용자 빌드 클라이언트가 필요한 상위 모듈(agent, voice)에는 영향을 주지 않습니다.
cd llm/gemini && go mod edit -require=github.com/joakimcarlsson/ai/[email protected] && go mod tidy
PR이 병합된 후, 캐스케이드된 각 모듈에 패치 번호(patch bump)를 태그해야 합니다. 이 연쇄적 업데이트 과정이 없으면, go get llm/gemini@latest를 실행하는 사용자는 MVS를 통해 이전 버전의 model을 받게 되며 새로운 상수는 빌드에서 해결되지 않습니다.
변경된 모듈이 공유 종속성이 아니거나(예: llm/anthropic 내부 수정), 모듈 자체의 go.mod만 변경된 경우(간접 종속성 증가, tidy 정리)에는 이 단계를 건너뜁니다. 이러한 경우는 소비자에게 보이는 영향이 없으며 태그가 전혀 필요하지 않습니다.
4. Go 모듈 프록시 워밍업 (Warm the Go module proxy)
scripts/release.sh warm -t llm/openai/v0.1.0
이는 태그가 지정된 버전이 go get을 통해 즉시 사용 가능하도록 보장합니다. 단계 2와 3에서 생성된 모든 태그에 대해 이 작업을 수행해야 합니다.
5. 날짜가 포함된 GitHub Release 생성 (Create a dated GitHub Release)
scripts/release.sh release
...
이는 release-YYYY-MM-DD 태그와 이전 릴리스 이후 생성된 모든 모듈 태그를 나열하는 GitHub Release를 생성합니다.
라이선스 (License)
LICENSE 파일을 참조하십시오.