안녕하세요. 저는 HolySheep AI의 시니어 엔지니어이자 기술 아키텍트입니다. 이번 포스트에서는 Google의 Gemini 2.5 Pro에서 제공하는 Function Calling 기능을 프로덕션 환경에서 효과적으로 활용하는 방법을 깊이 있게 다루겠습니다. 실제 프로젝트에서 경험한 최적화 기법과 벤치마크 데이터를 함께 공유하겠습니다.

Function Calling이란?

Function Calling은 LLM이 사용자가 정의한 함수를 호출할 수 있게 하는 메커니즘입니다. 단순히 텍스트를 생성하는 것이 아니라, 데이터베이스 조회, API 호출, 파일 시스템 접근, 계산 작업 등을 LLM이 직접 수행할 수 있게 합니다. Gemini 2.5 Pro는 특히 다중 도구 호출(Multi-turn Tool Use)과 긴 컨텍스트 처리에 강력한 성능을 보입니다.

아키텍처 설계 패턴

1. 동기식 vs 비동기식 호출 패턴

프로덕션 환경에서는 함수 실행 시간과 LLM 응답 시간의 균형이 중요합니다. 저는 일반적으로 다음과 같은 아키텍처를 권장합니다:

// HolySheep AI를 통한 Gemini 2.5 Pro Function Calling 설정
const { OpenAI } = require('openai');

const client = new OpenAI({
  baseURL: 'https://api.holysheep.ai/v1',
  apiKey: process.env.HOLYSHEEP_API_KEY,
});

// 함수 스키마 정의 - LLM이 호출할 수 있는 도구 설정
const functionDeclarations = [
  {
    name: 'get_weather',
    description: '특정 도시의 현재 날씨 정보를 조회합니다',
    parameters: {
      type: 'object',
      properties: {
        city: {
          type: 'string',
          description: '날씨를 조회할 도시 이름 (예: 서울, 도쿄)'
        },
        unit: {
          type: 'string',
          enum: ['celsius', 'fahrenheit'],
          description: '온도 단위',
          default: 'celsius'
        }
      },
      required: ['city']
    }
  },
  {
    name: 'search_database',
    description: '내부 데이터베이스에서 정보를 검색합니다',
    parameters: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: '검색할 키워드'
        },
        limit: {
          type: 'integer',
          description: '반환할 결과 수',
          default: 10
        }
      },
      required: ['query']
    }
  },
  {
    name: 'calculate_route',
    description: '두 지점 간의 최적 경로를 계산합니다',
    parameters: {
      type: 'object',
      properties: {
        start: { type: 'string' },
        end: { type: 'string' },
        mode: {
          type: 'string',
          enum: ['driving', 'walking', 'transit'],
          default: 'driving'
        }
      },
      required: ['start', 'end']
    }
  }
];

// Function Calling 요청 예제
async function callWithFunction(message) {
  const response = await client.chat.completions.create({
    model: 'gemini-2.5-pro',
    messages: [
      { role: 'user', content: message }
    ],
    tools: functionDeclarations.map(func => ({
      type: 'function',
      function: func
    })),
    tool_choice: 'auto',  // LLM이 자동으로 함수 선택
    temperature: 0.7,
    max_tokens: 2048
  });

  return response;
}

2. 다중 함수 연속 호출 아키텍처

Gemini 2.5 Pro의 강력한 기능 중 하나는 연속적인 함수 호출입니다. 한 번의 요청에서 여러 함수를 순차적으로 호출하고 결과를 취합할 수 있습니다.

// 다중 함수 연속 호출 처리
async function multiFunctionCall(userMessage) {
  const messages = [
    { role: 'user', content: userMessage }
  ];
  
  const maxIterations = 5;  // 최대 호출 횟수 제한
  let iteration = 0;
  
  while (iteration < maxIterations) {
    const response = await client.chat.completions.create({
      model: 'gemini-2.5-pro',
      messages: messages,
      tools: functionDeclarations.map(func => ({
        type: 'function',
        function: func
      })),
      temperature: 0.3,
      max_tokens: 4096
    });

    const assistantMessage = response.choices[0].message;
    messages.push(assistantMessage);

    // 도구 호출이 없는 경우 완료
    if (!assistantMessage.tool_calls || assistantMessage.tool_calls.length === 0) {
      return {
        finalResponse: assistantMessage.content,
        totalIterations: iteration + 1,
        tokensUsed: response.usage.total_tokens
      };
    }

    // 각 도구 호출 결과 처리
    for (const toolCall of assistantMessage.tool_calls) {
      const functionName = toolCall.function.name;
      const args = JSON.parse(toolCall.function.arguments);
      
      console.log(함수 호출: ${functionName}, args);
      
      // 실제 함수 실행
      const functionResult = await executeFunction(functionName, args);
      
      // 도구 결과 메시지 추가
      messages.push({
        role: 'tool',
        tool_call_id: toolCall.id,
        content: JSON.stringify(functionResult)
      });
    }

    iteration++;
  }

  throw new Error('최대 반복 횟수 초과');
}

// 함수 실행 핸들러
async function executeFunction(name, args) {
  const functions = {
    get_weather: async ({ city, unit }) => {
      // 실제 API 호출 시뮬레이션
      return {
        city: city,
        temperature: 23,
        condition: '맑음',
        humidity: 65,
        timestamp: new Date().toISOString()
      };
    },
    search_database: async ({ query, limit }) => {
      return {
        query: query,
        results: [
          { id: 1, title: '결과 1', score: 0.95 },
          { id: 2, title: '결과 2', score: 0.87 }
        ].slice(0, limit)
      };
    },
    calculate_route: async ({ start, end, mode }) => {
      return {
        start: start,
        end: end,
        mode: mode,
        distance: '15.3km',
        duration: '25분',
        route: ['포인트A', '포인트B', '포인트C']
      };
    }
  };

  if (!functions[name]) {
    throw new Error(알 수 없는 함수: ${name});
  }

  return functions[name](args);
}

성능 최적화와 벤치마크

응답 시간 및 비용 분석

HolySheep AI 게이트웨이를 통한 Gemini 2.5 Pro 성능을 실제 환경에서 측정했습니다:

비용 최적화 전략

프로덕션 환경에서 비용을 절감하기 위한 핵심 전략을 설명드리겠습니다. 저는 매달 수백만 건의 API 호출을 관리하는데, 이 과정에서 축적된 경험입니다.

// 비용 최적화된 Function Calling 구현
class OptimizedFunctionCaller {
  constructor(apiKey) {
    this.client = new OpenAI({
      baseURL: 'https://api.holysheep.ai/v1',
      apiKey: apiKey,
    });
    this.cache = new Map();
    this.stats = { calls: 0, cacheHits: 0, costs: 0 };
  }

  // 응답 캐싱으로 중복 호출 방지
  async callWithCache(userMessage, ttlSeconds = 300) {
    const cacheKey = this.hashMessage(userMessage);
    
    // 캐시 히트 시
    if (this.cache.has(cacheKey)) {
      const cached = this.cache.get(cacheKey);
      if (Date.now() - cached.timestamp < ttlSeconds * 1000) {
        this.stats.cacheHits++;
        console.log(캐시 히트: ${cacheKey});
        return cached.result;
      }
    }

    // 새 요청 실행
    this.stats.calls++;
    const startTime = Date.now();
    const result = await this.callWithFunction(userMessage);
    const latency = Date.now() - startTime;

    // 비용 계산 및 기록
    const cost = this.calculateCost(result);
    this.stats.costs += cost;

    // 결과 캐싱
    this.cache.set(cacheKey, {
      result,
      timestamp: Date.now(),
      latency,
      cost
    });

    return result;
  }

  // 비용 계산
  calculateCost(response) {
    const usage = response.usage;
    const inputCost = (usage.prompt_tokens / 1000000) * 3.50;  // $3.50/MTok
    const outputCost = (usage.completion_tokens / 1000000) * 7.00;  // $7.00/MTok
    return inputCost + outputCost;
  }

  // 메시지 해시 생성
  hashMessage(message) {
    const crypto = require('crypto');
    return crypto.createHash('sha256').update(message).digest('hex');
  }

  // 통계 반환
  getStats() {
    return {
      ...this.stats,
      cacheHitRate: (this.stats.cacheHits / this.stats.calls * 100).toFixed(2) + '%',
      totalCost: '$' + this.stats.costs.toFixed(4)
    };
  }

  // 배치 처리로 비용 절감
  async batchCall(messages, batchSize = 5) {
    const results = [];
    for (let i = 0; i < messages.length; i += batchSize) {
      const batch = messages.slice(i, i + batchSize);
      const batchPromises = batch.map(msg => this.callWithCache(msg));
      const batchResults = await Promise.all(batchPromises);
      results.push(...batchResults);
      
      // 배치 간 딜레이로 Rate Limit 방지
      if (i + batchSize < messages.length) {
        await this.delay(500);
      }
    }
    return results;
  }

  delay(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

// 사용 예제
const caller = new OptimizedFunctionCaller(process.env.HOLYSHEEP_API_KEY);

const testMessages = [
  '서울의 날씨를 알려주세요',
  '데이터베이스에서 AI 관련 정보를 검색해주세요',
  '서울에서 부산까지 경로를 계산해주세요'
];

const results = await caller.batchCall(testMessages);
console.log('결과:', results);
console.log('통계:', caller.getStats());

동시성 제어와 Rate Limit 관리

대규모 프로덕션 환경에서는 동시성 제어와 Rate Limit 관리가 필수적입니다. HolySheep AI 게이트웨이는 분당 요청 수(RPM)와 분당 토큰 수(TPM) 제한을 적용하므로, 이를 고려한 설계가 필요합니다.

// 동시성 제어 및 Rate Limit 관리
class RateLimitedFunctionCaller {
  constructor(apiKey, options = {}) {
    this.client = new OpenAI({
      baseURL: 'https://api.holysheep.ai/v1',
      apiKey: apiKey,
    });
    
    // Rate Limit 설정 (HolySheep AI 기본값 기준)
    this.rpmLimit = options.rpmLimit || 60;
    this.tpmLimit = options.tpmLimit || 1000000;
    
    this.requestQueue = [];
    this.activeRequests = 0;
    this.tokenUsage = { prompt: 0, completion: 0, resetTime: Date.now() };
    
    // 요청 큐 처리 시작
    this.startQueueProcessor();
  }

  startQueueProcessor() {
    setInterval(() => this.processQueue(), 100);
    
    // TPM 리셋 (1분마다)
    setInterval(() => {
      this.tokenUsage = { prompt: 0, completion: 0, resetTime: Date.now() };
      console.log('TPM 카운터 리셋');
    }, 60000);
  }

  async acquireToken(tokens) {
    const waitTime = 100;
    const maxWait = 30000;
    let waited = 0;

    while (this.tokenUsage.prompt + tokens > this.tpmLimit) {
      if (waited >= maxWait) {
        throw new Error('토큰 할당 대기 시간 초과');
      }
      await this.delay(waitTime);
      waited += waitTime;
    }

    this.tokenUsage.prompt += tokens;
  }

  async acquireSlot() {
    const waitTime = 50;
    const maxWait = 15000;
    let waited = 0;

    while (this.activeRequests >= this.rpmLimit) {
      if (waited >= maxWait) {
        throw new Error('동시 요청 슬롯 대기 시간 초과');
      }
      await this.delay(waitTime);
      waited += waitTime;
    }

    this.activeRequests++;
  }

  async callWithFunction(message, functionDeclarations) {
    return new Promise((resolve, reject) => {
      this.requestQueue.push({ message, functionDeclarations, resolve, reject });
    });
  }

  async processQueue() {
    if (this.requestQueue.length === 0) return;
    if (this.activeRequests >= this.rpmLimit) return;

    const request = this.requestQueue.shift();
    
    try {
      await this.acquireSlot();
      
      // 예상 토큰 수 기반 Rate Limit 체크
      const estimatedTokens = request.message.length / 4;  // 대략적估算
      await this.acquireToken(estimatedTokens);

      const response = await this.executeCall(request);
      this.activeRequests--;
      request.resolve(response);
      
    } catch (error) {
      this.activeRequests--;
      request.reject(error);
    }
  }

  async executeCall(request) {
    return this.client.chat.completions.create({
      model: 'gemini-2.5-pro',
      messages: [{ role: 'user', content: request.message }],
      tools: request.functionDeclarations,
      temperature: 0.5,
      max_tokens: 2048
    });
  }

  delay(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }

  getStatus() {
    return {
      activeRequests: this.activeRequests,
      queueLength: this.requestQueue.length,
      tokenUsage: this.tokenUsage,
      rpmUsage: ${this.activeRequests}/${this.rpmLimit},
      tpmUsage: ${this.tokenUsage.prompt}/${this.tpmLimit}
    };
  }
}

// 사용 예제
const rateLimitedCaller = new RateLimitedFunctionCaller(
  process.env.HOLYSHEEP_API_KEY,
  { rpmLimit: 60, tpmLimit: 1000000 }
);

// 동시 요청 테스트
async function stressTest() {
  const promises = Array(100).fill(null).map((_, i) => 
    rateLimitedCaller.callWithFunction(
      테스트 요청 ${i},
      functionDeclarations
    ).then(r => ({ id: i, tokens: r.usage.total_tokens }))
  );

  const start = Date.now();
  const results = await Promise.allSettled(promises);
  const duration = Date.now() - start;

  console.log(100개 동시 요청 완료: ${duration}ms);
  console.log(평균 응답 시간: ${(duration / 100).toFixed(2)}ms);
  console.log(상태:, rateLimitedCaller.getStatus());
}

에러 처리와 재시도 메커니즘

프로덕션 환경에서는 네트워크 오류, Rate Limit, 서비스 일시 중단 등 다양한 예외 상황을 처리해야 합니다. 저는 지수 백오프(Exponential Backoff)와 서킷 브레이커 패턴을 combination하여 안정적인 시스템을 구축했습니다.

// 탄력적인 에러 처리 및 재시도 로직
class ResilientFunctionCaller {
  constructor(apiKey) {
    this.client = new OpenAI({
      baseURL: 'https://api.holysheep.ai/v1',
      apiKey: apiKey,
    });
    
    // 서킷 브레이커 상태
    this.circuitState = 'CLOSED';  // CLOSED, OPEN, HALF_OPEN
    this.failureCount = 0;
    this.successCount = 0;
    this.lastFailureTime = null;
    
    // 설정값
    this.failureThreshold = 5;
    this.successThreshold = 3;
    this.timeout = 30000;
    this.halfOpenMaxCalls = 3;
    this.halfOpenCalls = 0;
  }

  async callWithRetry(message, functionDeclarations, options = {}) {
    const maxRetries = options.maxRetries || 3;
    const baseDelay = options.baseDelay || 1000;
    const maxDelay = options.maxDelay || 10000;

    let lastError;
    
    for (let attempt = 0; attempt <= maxRetries; attempt++) {
      // 서킷 브레이커 체크
      if (this.circuitState === 'OPEN') {
        if (Date.now() - this.lastFailureTime > this.timeout) {
          this.circuitState = 'HALF_OPEN';
          this.halfOpenCalls = 0;
          console.log('서킷 브레이커: HALF_OPEN 상태로 전환');
        } else {
          throw new Error('서킷 브레이커가 OPEN 상태입니다. 잠시 후 재시도해주세요.');
        }
      }

      try {
        const response = await this.executeCall(message, functionDeclarations);
        this.handleSuccess();
        return response;
        
      } catch (error) {
        lastError = error;
        console.error(시도 ${attempt + 1} 실패:, error.message);
        
        // 재시도 불가 오류 체크
        if (!this.isRetryable(error)) {
          this.handleFailure();
          throw error;
        }

        // 마지막 시도인 경우
        if (attempt === maxRetries) {
          this.handleFailure();
          break;
        }

        // 지수 백오프 계산
        const delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
        const jitter = Math.random() * delay * 0.1;
        
        console.log(${delay + jitter}ms 후 재시도...);
        await this.sleep(delay + jitter);
      }
    }

    throw lastError;
  }

  async executeCall(message, functionDeclarations) {
    return this.client.chat.completions.create({
      model: 'gemini-2.5-pro',
      messages: [{ role: 'user', content: message }],
      tools: functionDeclarations,
      timeout: 30000
    });
  }

  isRetryable(error) {
    const retryableCodes = [
      429,  // Rate Limit
      500,  // Internal Server Error
      502,  // Bad Gateway
      503,  // Service Unavailable
      504   // Gateway Timeout
    ];

    const retryableMessages = [
      'rate limit',
      'timeout',
      'temporarily unavailable',
      'service unavailable'
    ];

    return retryableCodes.includes(error.status) ||
           retryableMessages.some(msg => error.message?.toLowerCase().includes(msg));
  }

  handleSuccess() {
    this.failureCount = 0;
    this.successCount++;
    
    if (this.circuitState === 'HALF_OPEN') {
      if (this.successCount >= this.successThreshold) {
        this.circuitState = 'CLOSED';
        this.successCount = 0;
        console.log('서킷 브레이커: CLOSED 상태로 전환 (복구 완료)');
      }
    }
  }

  handleFailure() {
    this.failureCount++;
    this.successCount = 0;
    this.lastFailureTime = Date.now();

    if (this.circuitState === 'HALF_OPEN') {
      this.halfOpenCalls++;
      if (this.halfOpenCalls >= this.halfOpenMaxCalls) {
        this.circuitState = 'OPEN';
        console.log('서킷 브레이커: OPEN 상태로 전환 (연속 실패)');
      }
    } else if (this.failureCount >= this.failureThreshold) {
      this.circuitState = 'OPEN';
      console.log('서킷 브레이커: OPEN 상태로 전환 (임계값 초과)');
    }
  }

  sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
  }

  getCircuitStatus() {
    return {
      state: this.circuitState,
      failureCount: this.failureCount,
      successCount: this.successCount,
      lastFailureTime: this.lastFailureTime
    };
  }
}

// 사용 예제
const resilientCaller = new ResilientFunctionCaller(process.env.HOLYSHEEP_API_KEY);

async function robustCall() {
  try {
    const response = await resilientCaller.callWithRetry(
      '서울의 날씨를 알려주세요',
      functionDeclarations,
      { maxRetries: 3, baseDelay: 1000 }
    );
    console.log('성공:', response);
  } catch (error) {
    console.error('완전 실패:', error.message);
  }
  
  console.log('서킷 상태:', resilientCaller.getCircuitStatus());
}

실전 활용 사례: 대화형 주문 시스템

제가 실제로 구축한 사례를 공유드리겠습니다. Function Calling을 활용한 AI 주문 어시스턴트 시스템입니다. 사용자가 자연어로 상품을 검색하고, 재고를 확인하고, 주문을 완료하는 전체 플로우를 구현했습니다.

// 실전 활용: AI 주문 어시스턴트
class OrderAssistant {
  constructor(apiKey) {
    this.client = new OpenAI({
      baseURL: 'https://api.holysheep.ai/v1',
      apiKey: apiKey,
    });
    
    // 주문 관련 함수 정의
    this.orderFunctions = [
      {
        name: 'search_products',
        description: '사용자의 요청에 맞는 상품을 검색합니다',
        parameters: {
          type: 'object',
          properties: {
            keyword: { type: 'string', description: '검색 키워드' },
            category: { type: 'string', description: '상품 카테고리' },
            price_range: {
              type: 'object',
              properties: {
                min: { type: 'number' },
                max: { type: 'number' }
              }
            }
          }
        }
      },
      {
        name: 'check_inventory',
        description: '상품의 재고를 확인합니다',
        parameters: {
          type: 'object',
          properties: {
            product_id: { type: 'string' }
          },
          required: ['product_id']
        }
      },
      {
        name: 'calculate_price',
        description: '할인 및 배송비를 포함한 최종 가격을 계산합니다',
        parameters: {
          type: 'object',
          properties: {
            product_id: { type: 'string' },
            quantity: { type: 'integer', minimum: 1 },
            coupon_code: { type: 'string' }
          },
          required: ['product_id', 'quantity']
        }
      },
      {
        name: 'create_order',
        description: '최종 주문을 생성합니다',
        parameters: {
          type: 'object',
          properties: {
            product_id: { type: 'string' },
            quantity: { type: 'integer' },
            shipping_address: { type: 'string' },
            payment_method: {
              type: 'string',
              enum: ['credit_card', 'bank_transfer', 'mobile_payment']
            }
          },
          required: ['product_id', 'quantity', 'shipping_address', 'payment_method']
        }
      }
    ];

    this.conversationHistory = [];
    this.orderContext = {};
  }

  async processMessage(userMessage) {
    this.conversationHistory.push({
      role: 'user',
      content: userMessage
    });

    let iteration = 0;
    const maxIterations = 6;

    while (iteration < maxIterations) {
      const response = await this.client.chat.completions.create({
        model: 'gemini-2.5-pro',
        messages: this.conversationHistory,
        tools: this.orderFunctions.map(f => ({
          type: 'function',
          function: f
        })),
        tool_choice: 'auto',
        temperature: 0.7
      });

      const assistantMessage = response.choices[0].message;
      this.conversationHistory.push(assistantMessage);

      // 도구 호출이 없으면 종료
      if (!assistantMessage.tool_calls) {
        return {
          message: assistantMessage.content,
          context: this.orderContext,
          cost: this.calculateCost(response.usage)
        };
      }

      // 도구 실행
      for (const toolCall of assistantMessage.tool_calls) {
        const result = await this.executeTool(toolCall);
        
        this.conversationHistory.push({
          role: 'tool',
          tool_call_id: toolCall.id,
          content: JSON.stringify(result)
        });

        // 주문 완료 시 컨텍스트 업데이트
        if (toolCall.function.name === 'create_order' && result.success) {
          this.orderContext.completedOrder = result;
        }
      }

      iteration++;
    }

    return {
      message: '주문 처리가 최대 반복 횟수를 초과했습니다. 고객센터에 문의해주세요.',
      context: this.orderContext
    };
  }

  async executeTool(toolCall) {
    const { name, arguments: argsStr } = toolCall.function;
    const args = JSON.parse(argsStr);

    switch (name) {
      case 'search_products':
        return this.mockSearchProducts(args);
      case 'check_inventory':
        return this.mockCheckInventory(args);
      case 'calculate_price':
        return this.mockCalculatePrice(args);
      case 'create_order':
        return this.mockCreateOrder(args);
      default:
        throw new Error(알 수 없는 함수: ${name});
    }
  }

  // Mock 함수들 (실제로는 데이터베이스/API 호출)
  mockSearchProducts({ keyword, category, price_range }) {
    const products = [
      { id: 'P001', name: '노트북 Pro 15', price: 1500000, category: '전자제품' },
      { id: 'P002', name: '무선 키보드', price: 89000, category: '주변기기' },
      { id: 'P003', name: 'USB-C 허브', price: 45000, category: '주변기기' }
    ];

    return {
      products: products.filter(p => {
        if (keyword && !p.name.includes(keyword)) return false;
        if (category && p.category !== category) return false;
        if (price_range) {
          if (price_range.min && p.price < price_range.min) return false;
          if (price_range.max && p.price > price_range.max) return false;
        }
        return true;
      }),
      total: 3
    };
  }

  mockCheckInventory({ product_id }) {
    return {
      product_id,
      available: true,
      quantity: 15,
      estimated_delivery: '2-3일'
    };
  }

  mockCalculatePrice({ product_id, quantity, coupon_code }) {
    const basePrice = 1500000;
    let discount = 0;

    if (coupon_code === 'SAVE10') discount = 0.1;
    else if (coupon_code === 'SAVE20') discount = 0.2;

    const subtotal = basePrice * quantity;
    const discountAmount = subtotal * discount;
    const shipping = quantity > 2 ? 0 : 3000;
    const total = subtotal - discountAmount + shipping;

    return {
      subtotal,
      discount: discountAmount,
      shipping,
      total,
      currency: 'KRW'
    };
  }

  mockCreateOrder({ product_id, quantity, shipping_address, payment_method }) {
    return {
      success: true,
      order_id: ORD-${Date.now()},
      product_id,
      quantity,
      shipping_address,
      payment_method,
      status: 'confirmed',
      total: 1500000 * quantity + 3000
    };
  }

  calculateCost(usage) {
    const inputCost = (usage.prompt_tokens / 1000000) * 3.50;
    const outputCost = (usage.completion_tokens / 1000000) * 7.00;
    return { inputCost, outputCost, total: inputCost + outputCost };
  }

  reset() {
    this.conversationHistory = [];
    this.orderContext = {};
  }
}

// 주문 어시스턴트 사용 예제
async function testOrderAssistant() {
  const assistant = new OrderAssistant(process.env.HOLYSHEEP_API_KEY);

  // 대화형 주문 시나리오
  const conversation = [
    '노트북을 찾고 있는데 100만원 이하로 보여줘',
    'P001의 재고가 있나요?',
    '2개订购하고 쿠폰 SAVE10 적용하면 얼마예요?',
    '서울시 강남구으로 배송, 신용카드로 결제할게요'
  ];

  for (const message of conversation) {
    console.log(\n사용자: ${message});
    const result = await assistant.processMessage(message);
    console.log(AI 응답: ${result.message});
    if (result.cost) {
      console.log(비용: $${result.cost.total.toFixed(4)});
    }
  }
}

자주 발생하는 오류와 해결책

1. Rate Limit 초과 오류 (429)

Rate Limit 초과 시 가장 흔하게 발생하는 오류입니다. HolySheep AI는 분당 요청 수와 토큰 수에 제한을设정하고 있습니다.

// Rate Limit 오류 처리
async function handleRateLimitError() {
  try {
    const response = await client.chat.completions.create({
      model: 'gemini-2.5-pro',
      messages: [{ role: 'user', content: '테스트 메시지' }],
      tools: functionDeclarations
    });
  } catch (error) {
    if (error.status === 429) {
      // Retry-After 헤더 확인
      const retryAfter = error.headers?.['retry-after'] || 60;
      console.log(Rate Limit 초과. ${retryAfter}초 후 재시도...);
      
      // 지수 백오프와 함께 재시도
      await sleep(retryAfter * 1000);
      
      // 재시도 로직 구현
      return retryWithBackoff(message, maxRetries - 1);
    }
    throw error;
  }
}

// 분당 요청 수 모니터링
function checkRateLimit(headers) {
  const remaining = parseInt(headers['x-ratelimit-remaining'] || '60');
  const reset = parseInt(headers['x-ratelimit-reset'] || Date.now() + 60000);
  
  if (remaining < 10) {
    console.warn(⚠️ Rate Limit 임박! 남은 요청: ${remaining});
    console.log(리셋 시간: ${new Date(reset).toISOString()});
  }
  
  return { remaining, reset };
}

2. 함수 파라미터 타입 불일치 오류

Function Calling에서 가장 흔한 실수는 JSON 스키마 정의와 실제 파라미터 타입의 불일치입니다.

// ❌ 잘못된 정의
const badSchema = {
  name: 'get_user_info',
  parameters: {
    type: 'object',
    properties: {
      user_id: {
        type: 'string',  // number로 넘겨주는 경우가 많음
        description: '사용자 ID'
      },
      include_stats: {
        type: 'boolean'  // 문자열 "true"로 오는 경우가 많음
      }
    }
  }
};

// ✅ 올바른 정의 (strict 타입 처리)
const correctSchema = {
  name: 'get_user_info',
  parameters: {
    type: 'object',
    properties: {
      user_id: {
        type: 'string',
        description: '사용자 ID (문자열 또는 숫자)'
      },
      include_stats: {
        type: 'string',  // enum 대신 string으로 변경
        enum: ['true', 'false'],
        description: '통계 포함 여부'
      }
    }
  }
};

// 파라미터 정규화 함수
function normalizeParameters(args, schema) {
  const normalized = {};
  
  for (const [key, value] of Object.entries(args)) {
    const paramDef = schema.properties[key];
    
    if (paramDef.type === 'string' && typeof value !== 'string') {
      normalized[key] = String(value);
    } else if (paramDef.type === 'number' && typeof value === 'string') {
      normalized[key] = parseFloat(value) || 0;
    } else if (paramDef.enum && !paramDef.enum.includes(value)) {
      normalized[key] = paramDef.enum[0];  // 기본값 사용
    } else {
      normalized[key] = value;
    }
  }
  
  return normalized;
}

// 사용
const rawArgs = JSON.parse(toolCall.function.arguments);
const cleanArgs = normalizeParameters(rawArgs, correctSchema);

3. 토큰 초과 오류 (context length)

긴 대화 히스토리나 큰 함수 결과로 인해 컨텍스트 길이를 초과하는 경우입니다.

// 컨텍스트 길이 관리
class ContextManager {
  constructor(maxTokens = 100000) {
    this.maxTokens = maxTokens;
    this.messages = [];
  }

  addMessage(role, content) {
    this.messages.push({ role, content, tokens: this.estimateTokens(content) });
    this.trimContext();
  }

  estimateTokens(text) {
    // 한글 기준: 1글자 ≈ 2 토큰, 영문: 1단어 ≈ 1.3 토큰
    const koreanChars = (text.match(/[가-힣]/g) || []).length;
    const otherChars = text.length - koreanChars;
    return Math.ceil(koreanChars * 2 + otherChars / 4);
  }

  trimContext() {
    let totalTokens = this.messages.reduce((sum, m) => sum + m.tokens, 0);
    
    while (totalTokens > this.maxTokens && this.messages.length > 2) {
      // 가장 오래된 사용자 메시지와 AI 응답을 쌍으로 제거
      this.messages.shift();  // 오래된 사용자 메시지
      if (this.messages[0]?.role === 'assistant') {
        this.messages.shift();  // 해당 AI 응답
      }
      
      totalTokens = this.messages.reduce((sum, m) => sum + m.tokens, 0);
    }
    
    console.log(컨텍스트 트리밍 완료. 현재 ${totalTokens} 토큰);
  }

  getMessages() {
    return this.messages.map(m => ({ role: m.role, content: m.content }));
  }

  // 함수 결과를 요약하여 저장 (토큰 절약)
  summarizeFunctionResult(result) {
    if (typeof result === 'object') {
      // 핵심 정보만 추출
      return JSON.stringify({
        summary: true,
        key_info: Object.keys(result).slice(0, 5).reduce((acc, key) => {
          acc[key] = result[key];
          return acc;
        }, {}),
        original_length: JSON.stringify(result).length
      });
    }
    return String(result).substring(0, 500) + '...';
  }
}

4. 함수 응답 형식 오류

도구 함수에서 반환하는 형식이 잘못되어 LLM이 결과를 올바르게 해석하지 못하는 경우입니다.

// 올바른 함수 응답 형식
function formatToolResponse(result, success = true) {
  if (success) {
    return {
      status:

관련 리소스
관련 문서