**저자**: HolySheep AI 기술 문서팀
Coze(코즈)는 비트로이스(ByteDance)에서 개발한 AI 챗봇 개발 플랫폼으로, 코딩 없이도 강력한 AI 에이전트를 만들 수 있습니다. 하지만 Coze에서 더 고급 기능을 활용하거나 비용을 최적화하려면 HolySheep AI 게이트웨이를 함께 사용하는 것이 가장 효과적입니다.
이 가이드에서는 Coze의 플러그인 설정과 지식 베이스 구성, 그리고 HolySheep AI를 통한 API 연결 최적화까지 완전 초보자도 따라할 수 있도록 단계별로 설명드리겠습니다.
---
1. Coze 플랫폼 기본 개념 이해
1.1 Coze란 무엇인가?
Coze는 **Bot(봇)**라고 부르는 AI 에이전트를 만들 수 있는 플랫폼입니다. 마치 레고 블록을 조립하듯 다양한 기능을 연결하여 챗봇을 만들 수 있습니다.
**Coze의 주요 구성 요소**:
| 구성 요소 | 설명 | 비유 |
|-----------|------|------|
| Bot | 만들어지는 AI 챗봇 | 완성된 레고 작품 |
| Plugin | 외부 도구나 서비스 연결 | 레고 블록의 기능 부품 |
| Knowledge Base |自有 데이터로 학습 | 챗봇의 참고 도서관 |
| Workflow | 자동화된 작업 흐름 | 레고 블록의 연결 방식 |
1.2 HolySheep AI가 필요한 이유
저는 실제 프로젝트에서 Coze만 사용할 때 여러 가지 제약에 부딪혔습니다. 예를 들어, API 호출 빈도 제한이 엄격하고 비용 관리가 어렵습니다. **HolySheep AI**를 게이트웨이로 사용하면:
- **단일 API 키**로 GPT-4.1, Claude, Gemini, DeepSeek 등 모든 주요 모델 통합
- **비용 최적화**: GPT-4.1 $8/MTok, DeepSeek V3.2 $0.42/MTok의 경쟁력 있는 가격
- **해외 신용카드 없이 로컬 결제** 지원
- **가입 시 무료 크레딧** 제공으로 즉시 테스트 가능
👉
지금 HolySheep AI에 가입하여 무료 크레딧을 받으세요!
---
2. Coze 플러그인(Plugin) 설정 완벽 가이드
2.1 플러그인이란?
플러그인은 Coze 챗봇이 **외부 서비스나 도구**를 사용할 수 있게 해주는 연결고리입니다. 예를 들어:
- **날씨 확인**: 날씨 API에 연결하여 "내일 날씨가怎样?" 질문에 답변
- **영화 정보**: IMDb API로 영화 평점 검색
- **뉴스 수집**: RSS 피드로 최신 뉴스 제공
2.2 Coze에서 기본 플러그인 활성화하기
**步骤 1**: Coze 플랫폼에 로그인 후 Bots 섹션으로 이동합니다
[화면 예상 내용]
┌─────────────────────────────────────────┐
│ Bots Plugins Knowledge Workflows │
├─────────────────────────────────────────┤
│ │
│ [+ Create Bot] [My Bots] [Team Bots] │
│ │
└─────────────────────────────────────────┘
**步骤 2**: 새로운 Bot을 만들거나 기존 Bot을 선택합니다
**步骤 3**: Bot 편집 화면에서 왼쪽 패널의 "Plugin" 섹션을 찾습니다
[화면 예상 내용 - Plugin 패널]
┌─────────────────────────────────────┐
│ ⚡ Plugins [+] │
├─────────────────────────────────────┤
│ 🔍 Search plugins... │
│ │
│ 📦 Built-in │
│ ☑ Bing Search │
│ ☑ Google Search │
│ │
│ 🌐 API │
│ ☐ Weather API │
│ ☐ News API │
└─────────────────────────────────────┘
**步骤 4**: 원하는 플러그인을 체크하여 활성화합니다
2.3 커스텀 플러그인 추가하기
Coze에서는 직접 만든 플러그인을 연결할 수도 있습니다. REST API 기반의 플러그인을 만들어보겠습니다.
**事前 준비**:
- 플러그인으로 연결할 API가 필요합니다
- API가 REST 형식을 지원해야 합니다
- API 문서에서 엔드포인트, 메서드, 파라미터를 확인하세요
**단계별 설정**:
1. **Plugin 탭**에서 "Custom" 섹션의 "Add Plugin" 클릭
2. **Plugin 정보 입력**:
Plugin Name: 영화 정보 조회
Description: TMDB API를 사용하여 영화 정보를 검색합니다
Icon: 🎬 (선택)
3. **API 엔드포인트 설정**:
Method: GET
URL: https://api.themoviedb.org/3/search/movie
Headers:
- Authorization: Bearer {YOUR_TMDB_KEY}
- Content-Type: application/json
4. **파라미터 매핑**:
Query Parameters:
- query: 영화 제목 (필수)
- language: 언어 설정 (선택, 기본값: ko-KR)
Response Mapping:
- movies: results 배열
- title: title 필드
- overview: overview 필드
2.4 HolySheep AI와 플러그인 연동
이제 HolySheep AI를 사용하여 더 강력한 플러그인을 만들어보겠습니다. HolySheep AI의 API를 Coze 플러그인으로 연결하면 **다중 모델 앙상블**이 가능합니다.
// HolySheep AI API를 사용하는 Coze 플러그인 예시
// 이 플러그인은 HolySheep AI의 게이트웨이 기능을 활용합니다
const HOLYSHEEP_BASE_URL = 'https://api.holysheep.ai/v1';
const HOLYSHEEP_API_KEY = 'YOUR_HOLYSHEEP_API_KEY';
async function multiModelAnalysis(query) {
// 여러 모델의 결과를 비교 분석
const models = ['gpt-4.1', 'claude-sonnet-4-5', 'gemini-2.5-flash'];
const results = await Promise.all(
models.map(model =>
fetch(${HOLYSHEEP_BASE_URL}/chat/completions, {
method: 'POST',
headers: {
'Authorization': Bearer ${HOLYSHEEP_API_KEY},
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: model,
messages: [{ role: 'user', content: query }]
})
}).then(res => res.json())
)
);
return {
gpt_response: results[0].choices[0].message.content,
claude_response: results[1].choices[0].message.content,
gemini_response: results[2].choices[0].message.content
};
}
---
3. 지식 베이스(Knowledge Base) 구성 가이드
3.1 지식 베이스란?
지식 베이스는 Coze 챗봇이 **자체 데이터**를 학습하여 특정 주제에 대해 정확한 답변을 할 수 있게 해줍니다. 마치 챗봇에게 참고 도서를 주는 것과 같습니다.
**활용 예시**:
| 업종 | 지식 베이스 내용 | 효과 |
|------|------------------|------|
| 고객지원 | FAQ, 제품 매뉴얼 | 정확한 제품 답변 |
| 법률 | 법률条文, 판례 | 전문 법률 자문 |
| 교육 | 교재, 참고자료 | 학습 도우미 |
| 부동산 | 매물 정보, 지역 정보 | 부동산 상담 |
3.2 지식 베이스 만들기
**步骤 1**: Coze 좌측 메뉴에서 "Knowledge" 탭을 클릭합니다
[화면 예상 내용]
┌─────────────────────────────────────────┐
│ Bots Plugins Knowledge Workflows │
├─────────────────────────────────────────┤
│ │
│ [Knowledge] │
│ ┌───────────────────────────────────┐ │
│ │ 📚 My Knowledge Bases │ │
│ │ ───────────────────────────── │ │
│ │ [+ Create Knowledge] │ │
│ │ │ │
│ │ ┌─────────────────────────────┐ │ │
│ │ │ 📁 제품 매뉴얼 DB │ │ │
│ │ │ 파일: 25개 | 토큰: 120,000 │ │ │
│ │ │ 업데이트: 2024-01-15 │ │ │
│ │ └─────────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────┐ │ │
│ │ │ 📁 FAQ 데이터셋 │ │ │
│ │ │ 파일: 8개 | 토큰: 45,000 │ │ │
│ │ │ 업데이트: 2024-01-10 │ │ │
│ │ └─────────────────────────────┘ │ │
│ └───────────────────────────────────┘ │
└─────────────────────────────────────────┘
**步骤 2**: "Create Knowledge" 버튼을 클릭합니다
**步骤 3**: 지식 베이스 기본 정보 입력
Knowledge Name: 회사 제품 매뉴얼 (한글)
Description: 2024년 버전 제품 사용 설명서 및 사양서
Language: 한국어 (ko-KR)
Embedding Model: Coze Embedding (기본값)
3.3 데이터 파일 업로드하기
Coze는 다양한 파일 형식을 지원합니다:
**지원 형식**:
- **문서**: PDF, DOCX, TXT, MD
- **스프레드시트**: XLSX, CSV
- **웹페이지**: URL 입력으로 웹 컨텐츠 수집
- **Notion**: Notion 워크스페이스 연결
- **Confluence**: Atlassian Confluence 연결
**파일 업로드 방법**:
1. **Drag & Drop**: 파일을 업로드 영역에 드래그
2. **Click to Upload**: "Upload Files" 버튼 클릭 후 파일 선택
3. **URL 추가**: "Add URL"로 웹페이지 주소 입력
**최적화 팁**:
📋 파일 준비 체크리스트
□ 파일 크기: 100MB 이하 권장
□ 텍스트 인코딩: UTF-8 확인
□ 이미지 포함 PDF: OCR 처리된 텍스트 PDF 사용
□ 테이블 데이터: CSV 형식이 가장 안정적
□ 파일 이름: 한국어 파일명 사용 가능
□ 디렉토리 구조: 폴더별 분류로 나중에 관리 용이
3.4 데이터 청크(Chunk) 설정
지식 베이스의 핵심 설정 중 하나가 **청크(chunk) 크기**입니다. 이는 데이터를 얼마나 작게 나눠서 저장할지 결정합니다.
**청크 크기 선택 가이드**:
| 청크 크기 | 적합한 용도 | 예시 |
|-----------|-------------|------|
| 작게 (200-300토큰) | 상세 검색, 정확한 답변 | FAQ, 짧은 문단 |
| 중간 (500-800토큰) | 일반적인 문서 | 제품 설명, 기사 |
| 크게 (1000+토큰) | 맥락 유지 중요 | 소설, 논문 |
**설정 화면**:
[청크 설정 패널]
┌─────────────────────────────────────────┐
│ Chunk Settings │
├─────────────────────────────────────────┤
│ Chunk Size: [500] 토큰 │
│ │
│ Separation: [자동] ▼ │
│ • 자동 (권장) │
│ • 수동 분리자 지정 │
│ │
│ ☑ Remove extra spaces │
│ ☑ Remove special characters │
└─────────────────────────────────────────┘
3.5 HolySheep AI로 지식 베이스 검색 최적화
HolySheep AI의 DeepSeek 모델과 결합하면 **지식 베이스 검색 품질**을 크게 향상시킬 수 있습니다. 다음은 HolySheep AI를 활용한 RAG(Retrieval-Augmented Generation) 파이프라인 예시입니다.
# HolySheep AI를 사용한 향상된 RAG 검색 시스템
HolySheep AI의 DeepSeek V3.2 ($0.42/MTok) 모델로 비용 효율적인 검색
import requests
import json
class HolySheepRAGSearch:
def __init__(self):
self.api_key = 'YOUR_HOLYSHEEP_API_KEY'
self.base_url = 'https://api.holysheep.ai/v1'
def search_knowledge_base(self, query, knowledge_documents):
"""
Coze 지식 베이스 문서와 HolySheep AI를 결합한 검색
"""
# 1단계: 쿼리 이해 및 확장
query_expansion = self._expand_query(query)
# 2단계: 관련 문서 검색 (의미론적 검색)
relevant_docs = self._semantic_search(
query_expansion,
knowledge_documents
)
# 3단계: 컨텍스트 기반 답변 생성
context = self._build_context(relevant_docs)
response = self._generate_answer(query, context)
return {
'answer': response,
'sources': [doc['source'] for doc in relevant_docs],
'confidence': self._calculate_confidence(relevant_docs)
}
def _expand_query(self, query):
"""DeepSeek로 쿼리 확장 - synonyms, related terms"""
payload = {
'model': 'deepseek-v3.2',
'messages': [
{
'role': 'system',
'content': '입력된 질문과 관련된 추가 검색어를 생성해주세요.'
},
{
'role': 'user',
'content': f'원래 질문: {query}\n관련 검색어를 한 줄로 만들어주세요.'
}
],
'temperature': 0.3,
'max_tokens': 100
}
response = requests.post(
f'{self.base_url}/chat/completions',
headers={
'Authorization': f'Bearer {self.api_key}',
'Content-Type': 'application/json'
},
json=payload
)
return response.json()['choices'][0]['message']['content']
def _semantic_search(self, query, documents):
"""의미론적 유사도 기반 문서 검색"""
# Coze Knowledge Base API 호출 시뮬레이션
payload = {
'model': 'text-embedding-3-small',
'input': query
}
embedding_response = requests.post(
f'{self.base_url}/embeddings',
headers={
'Authorization': f'Bearer {self.api_key}',
'Content-Type': 'application/json'
},
json=payload
)
query_embedding = embedding_response.json()['data'][0]['embedding']
# 문서 유사도 계산 및 정렬
scored_docs = []
for doc in documents:
similarity = self._cosine_similarity(
query_embedding,
doc['embedding']
)
scored_docs.append({
**doc,
'score': similarity
})
return sorted(scored_docs, key=lambda x: x['score'], reverse=True)[:5]
def _generate_answer(self, query, context):
"""DeepSeek V3.2로 답변 생성 (비용 최적화)"""
payload = {
'model': 'deepseek-v3.2',
'messages': [
{
'role': 'system',
'content': '지식 베이스의 정보를 바탕으로 정확하게 답변해주세요.'
},
{
'role': 'user',
'content': f'질문: {query}\n\n참고 자료:\n{context}'
}
],
'temperature': 0.7,
'max_tokens': 1000
}
response = requests.post(
f'{self.base_url}/chat/completions',
headers={
'Authorization': f'Bearer {self.api_key}',
'Content-Type': 'application/json'
},
json=payload
)
return response.json()['choices'][0]['message']['content']
사용 예시
rag_system = HolySheepRAGSearch()
knowledge_docs = [
{'content': '제품 A의 사양은 다음과 같습니다...', 'source': 'manual.pdf'},
{'content': '제품 B는 다음 기능을 지원합니다...', 'source': 'spec.pdf'}
]
result = rag_system.search_knowledge_base('제품 A의 특징은?', knowledge_docs)
print(result)
---
4. Coze + HolySheep AI 통합 아키텍처
실제 프로젝트에서는 Coze와 HolySheep AI를 함께 사용하여 **최적의 결과**를 얻을 수 있습니다.
┌─────────────────────────────────────────────────────────────────┐
│ Coze + HolySheep AI 통합架构 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────────┐ ┌──────────────┐ │
│ │ User │────▶│ Coze Bot │────▶│ Plugin │ │
│ │ (사용자) │ │ (대화 인터페이스) │ │ (외부 도구) │ │
│ └──────────────┘ └──────────────────┘ └──────────────┘ │
│ │ │
│ │ Knowledge Base │
│ ▼ │
│ ┌──────────────────┐ │
│ │ 지식 베이스 │ │
│ │ (제품 문서/FAQ) │ │
│ └──────────────────┘ │
│ │ │
│ │ 필요시 Advanced API Call │
│ ▼ │
│ ┌──────────────┐ ┌──────────────────┐ ┌──────────────┐ │
│ │ Results │◀────│ HolySheep AI │◀────│ Models │ │
│ │ (결과) │ │ Gateway │ │ DeepSeek │ │
│ └──────────────┘ │ $0.42/MTok │ │ GPT-4.1 │ │
│ │ $8/MTok │ │ Claude │ │
│ └──────────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ 💰 비용 최적화 │
│ 📊 다중 모델 비교 │
│ 🔒 안정적인 연결 │
└─────────────────────────────────────────────────────────────────┘
---
5. 실전 프로젝트: 고객지원 챗봇 만들기
이제 이 모든 것을 종합하여 **실제 고객지원 챗봇**을 만들어보겠습니다.
5.1 프로젝트 요구사항
- 회사 제품에 대한 FAQ 자동 답변
- 주문 조회 기능
-HolySheep AI를 통한 다중 모델 답변 비교
5.2 Coze Bot 설정
**1단계: Bot 생성**
Bot Name: 고객지원 봇 v2.0
Description: 24시간 고객 문의를 자동응답하는 AI 챗봇
Icon: 🤖 (선택)
Language: 한국어
**2단계: 프롬프트 설정**
# 고객지원 봇 프롬프트
당신은 친절하고 전문적인 고객지원 상담원입니다.
기본 원칙
1. 항상 친절하고 공손한语气를 사용합니다
2. 모르는 것은 솔직히 "확인 후 답변드리겠습니다"라고 합니다
3. 구체적인 수치는 반드시 제품 사양서에서 확인합니다
4.投诉 사항은 즉시 담당 부서로 전달합니다
응답 형식
- 답변 끝에 관련 문서 링크를 포함합니다
- 명확한 단계별 안내를 제공합니다
- 필요시 이미지를 함께 공유합니다
**3단계: 플러그인 연결**
활성화된 플러그인:
☑ 날씨 정보 (고객 미팅 일정 참고용)
☑ HolySheep AI 다중 모델 분석 (복잡한 질문용)
☑ 주문 조회 시스템
**4단계: 지식 베이스 연결**
연결된 지식 베이스:
📚 제품 매뉴얼 2024 (120,000 토큰)
📚 FAQ 데이터셋 (45,000 토큰)
📚 정책 및 약관 (30,000 토큰)
5.3 HolySheep AI 통합 코드
```javascript
// Coze와 HolySheep AI 통합 - 고객지원 챗봇용
// 이 코드는 Coze의 Custom Plugin 또는 Workflow에서 사용됩니다
const HOLYSHEEP_BASE_URL = 'https://api.holysheep.ai/v1';
const HOLYSHEEP_API_KEY = 'YOUR_HOLYSHEEP_API_KEY';
// 모델별 가격표 (참고용)
// GPT-4.1: $8/MTok (고품질 응답)
// Claude Sonnet 4.5: $15/MTok (논리적 분석)
// Gemini 2.5 Flash: $2.50/MTok (빠른 응답)
// DeepSeek V3.2: $0.42/MTok (비용 최적화)
class CustomerSupportIntegration {
constructor() {
this.models = {
primary: 'gpt-4.1',
fast: 'gemini-2.5-flash',
analysis: 'claude-sonnet-4-5',
budget: 'deepseek-v3.2'
};
}
// 질문 유형 분류
async classifyQuery(userMessage) {
const response = await fetch(
${HOLYSHEEP_BASE_URL}/chat/completions, {
method: 'POST',
headers: {
'Authorization':
Bearer ${HOLYSHEEP_API_KEY},
'Content-Type': 'application/json'
},
body: JSON.stringify({
model: this.models.budget,
messages: [{
role: 'system',
content: '고객 문의를 다음 유형으로 분류해주세요: [기술문의/주문문의/불만/일반상담]'
}, {
role: 'user',
content: userMessage
}]
})
});
const result = await response.json();
return result.choices[0].message.content.trim();
}
// 기술 질문 - DeepSeek로 비용 절감
async handleTechnicalQuestion(question, knowledgeContext) {
const response = await fetch(
${HOLYSHEEP_BASE_URL}/chat/completions,