LLM 연결(LLM Connections)

LLM 연결(LLM Connections)

LLM 연결은 Langfuse Playground에서 모델을 호출하거나 LLM-as-a-Judge 평가에 사용됩니다. 이 문서는 LLM 연결을 설정하는 방법, 지원되는 제공자, 그리고 게이트웨이 연결이나 추가 제공자 옵션 같은 고급 구성을 설명해요.

출처: 문서

본문

LLM 연결은 Langfuse Playground에서 모델을 호출하거나 LLM-as-a-Judge 평가에 사용됩니다.

설정

• Project Settings > LLM Connections로 이동해 Add new LLM API key를 클릭합니다.
• LLM 연결의 이름과 사용하려는 모델의 API 키를 입력합니다.

API 를 사용해 LLM 연결을 관리할 수도 있습니다:

GET /api/public/llm-connections
PUT /api/public/llm-connections

지원되는 제공자

Langfuse 플랫폼은 현재 다음 LLM 제공자를 지원합니다:

• OpenAI
• Azure OpenAI
• Anthropic
• Google AI Studio
• Google Vertex AI
• Amazon Bedrock
• TypeSafe (실험적)

지원되는 모델

현재 Playground는 기본적으로 다음 모델을 지원합니다. Langfuse 프로젝트 설정에서 LLM API Key를 추가할 때 커스텀 모델 이름을 추가로 구성할 수 있습니다(예: 커스텀 모델이나 프록시를 사용하는 경우).

• OpenAI API 스키마를 지원하는 모든 모델: Playground와 LLM-as-a-Judge 평가는 Groq, OpenRouter, Vercel AI Gateway, LiteLLM, Hugging Face 등 OpenAI API 스키마를 지원하는 모든 프레임워크에서 사용할 수 있습니다. 사용하려는 모델에 맞는 엔드포인트로 API Base URL을 바꾸고 인증용 제공자 API 키를 추가하기만 하면 됩니다.
• OpenAI / Azure OpenAI: o3, o3-2025-04-16, o4-mini, o4-mini-2025-04-16, gpt-4.1, gpt-4.1-2025-04-14, gpt-4.1-mini-2025-04-14, gpt-4.1-nano-2025-04-14, gpt-4o, gpt-4o-2024-08-06, gpt-4o-2024-05-13, gpt-4o-mini, gpt-4o-mini-2024-07-18, o3-mini, o3-mini-2025-01-31, o1-preview, o1-preview-2024-09-12, o1-mini, o1-mini-2024-09-12, gpt-4-turbo-preview, gpt-4-1106-preview, gpt-4-0613, gpt-4-0125-preview, gpt-4, gpt-3.5-turbo-16k-0613, gpt-3.5-turbo-16k, gpt-3.5-turbo-1106, gpt-3.5-turbo-0613, gpt-3.5-turbo-0301, gpt-3.5-turbo-0125, gpt-3.5-turbo
• Anthropic: claude-3-7-sonnet-20250219, claude-3-5-sonnet-20241022, claude-3-5-sonnet-20240620, claude-3-opus-20240229, claude-3-sonnet-20240229, claude-3-5-haiku-20241022, claude-3-haiku-20240307, claude-2.1, claude-2.0, claude-instant-1.2
• Google Vertex AI: gemini-2.5-pro-exp-03-25, gemini-2.0-pro-exp-02-05, gemini-2.0-flash-001, gemini-2.0-flash-lite-preview-02-05, gemini-2.0-flash-exp, gemini-1.5-pro, gemini-1.5-flash, gemini-1.0-pro. Google Vertex AI 플랫폼이 지원하고 내 GCP 계정에서 활성화된 추가 모델 이름도 LLM API Key 생성 폼의 Custom model names 섹션에서 추가할 수 있습니다.
• Google AI Studio: gemini-2.5-pro-exp-03-25, gemini-2.0-flash, gemini-2.0-flash-lite-preview-02-05, gemini-2.0-flash-thinking-exp-01-21, gemini-1.5-pro, gemini-1.5-flash, gemini-1.5-flash-8b
• Amazon Bedrock: 모든 Amazon Bedrock 모델이 지원됩니다. AWS에 필요한 권한은 bedrock:InvokeModel과 bedrock:InvokeModelWithResponseStream입니다.

제3자 LLM 제공자가 지원되는 제공자 어댑터 중 하나의 스키마를 구현하면 연결할 수 있습니다. 예를 들어 Langfuse의 OpenAI 어댑터를 사용해 Mistral의 OpenAI 호환 API에 연결할 수 있습니다.

고급 구성

추가 제공자 옵션

제공자 옵션은 Project Settings > LLM Connections 페이지에서 설정하지 않으며, Playground 에서 LLM 연결을 선택하거나 LLM-as-a-Judge 평가자 설정 중에 설정합니다.

생성된 LLM 연결의 LLM 호출은 temperature, top_p, max_tokens 같은 특정 매개변수 집합으로 구성할 수 있습니다.

그러나 많은 LLM 제공자는 모델을 호출할 때 reasoning_effort, service_tier 등 추가 매개변수를 허용합니다. 이 매개변수들은 제공자마다 다른 경우가 많습니다.

모든 LLM 호출에 대해 JSON 객체로 추가 구성을 제공할 수 있습니다. 모델 매개변수 설정에서 맨 아래에 "provider options" 필드를 찾을 수 있습니다. 이 필드에 내 LLM 제공자 API 엔드포인트가 허용하는 특정 키-값 쌍을 입력할 수 있습니다.

추가 필드 지원에 대해서는 내 제공자의 API 참조를 확인하세요:

• Anthropic Messages API Reference
• OpenAI Chat Completions API Reference
• Google Gemini API Reference
• Google Vertex AI Gemini API Reference

이 기능은 현재 다음 제공자 어댑터에서 사용할 수 있습니다:

• Anthropic
• OpenAI
• Google AI Studio
• Google Vertex AI
• AWS (Amazon Bedrock)

OpenAI gpt-5 호출에서 reasoning effort를 minimal로 강제하는 예시가 있습니다. Google 모델(Google AI Studio, Google Vertex AI)에서 thinking을 제어하는 예시 제공자 옵션:

{
  "thinkingLevel": "MEDIUM",
  "thinkingBudget": 2048
}

thinkingLevel은 추론 깊이를 제어하고, thinkingBudget은 thinking을 위한 토큰 예산을 설정합니다. 이 옵션은 thinking을 지원하는 Google 모델에서만 유효합니다.

게이트웨이를 통한 연결

LiteLLM, OpenRouter, Portkey 같은 OpenAI 호환 게이트웨이로 LLM 호출을 라우팅한다면, 이를 Playground와 LLM-as-a-Judge 평가용 LLM 연결로 사용할 수 있습니다.

설정 방법:

• Project Settings > LLM Connections로 이동해 Add new LLM API key 클릭
• 제공자로 OpenAI 선택
• 게이트웨이의 API 키 입력
• Advanced Settings에서 Base URL을 게이트웨이 엔드포인트(예: https://your-litellm-instance.com/v1)로 설정
• 게이트웨이가 노출하는 custom model names 추가

LLM-as-a-Judge 평가가 동작하려면 게이트웨이가 tool calling 을 OpenAI 형식으로 지원해야 합니다.

OpenAI 호환 게이트웨이의 경우, Langfuse에서 LLM-as-a-Judge를 지원하려면 게이트웨이가 처리해야 하는 tool calling 요청 예시는 다음과 같습니다:

curl -X POST 'https://<host set in project settings>/chat/completions' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-H 'authorization: Bearer *** key entered in project settings>' \
-H 'x-test-header-1: <custom header set in project settings>' \
-H 'x-test-header-2: <custom header set in project settings>' \
-d '{
  "model": "<model set in project settings>",
  "temperature": 0,
  "top_p": 1,
  "frequency_penalty": 0,
  "presence_penalty": 0,
  "max_tokens": 256,
  "n": 1,
  "stream": false,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "extract",
        "parameters": {
          "type": "object",
          "properties": {
            "score": { "type": "string" },
            "reasoning": { "type": "string" }
          },
          "required": ["score", "reasoning"],
          "additionalProperties": false,
          "$schema": "http://json-schema.org/draft-07/schema#"
        }
      }
    }
  ],
  "tool_choice": {
    "type": "function",
    "function": { "name": "extract" }
  },
  "messages": [
    {
      "role": "user",
      "content": "Evaluate the correctness of the generation on a continuous scale from 0 to 1. ..."
    }
  ]
}'

OpenAI Responses API 엔드포인트

일부 OpenAI 호환 제공자는 Chat Completions API 대신 OpenAI Responses API 를 노출합니다. 이런 제공자에 대해서는 OpenAI LLM Connection에서 Use Responses API를 활성화해 Langfuse가 Playground, LLM-as-a-Judge, 프롬프트 실험 요청을 Responses API로 보내도록 하세요.

예를 들어 Bedrock Mantle 엔드포인트를 통해 Amazon Bedrock에서 OpenAI 모델을 사용하려면:

• Project Settings > LLM Connections로 이동해 Add new LLM API key 클릭
• 제공자로 OpenAI 선택
• 내 Amazon Bedrock API key 입력
• Advanced Settings에서 Base URL을 https://bedrock-mantle.<aws-region>.api.aws/openai/v1로 설정
• Use Responses API 활성화
• 내 Bedrock 계정에서 사용 가능한 custom model names 추가 (예: openai.gpt-5.5 또는 openai.gpt-5.4)

더 알아보기 (Learn more)

• 출처 문서: LLM 연결(LLM Connections)