차이

문서의 선택한 두 판 사이의 차이를 보여줍니다.

--- wiki:it:wiki:gemini_api_integration [2025/07/30 06:43] – 만듦 - 바깥 편집 127.0.0.1
+++ wiki:it:wiki:gemini_api_integration [2025/08/01 12:22] (현재) – syjang0803
@@ 줄 3: / 줄 3: @@
 이 문서는 DokuWiki와 Google Gemini API를 연동한 플러그인 개발에 대한 상세한 설명입니다.
-===== 아키텍처 개요 =====
+===== 1. 아키텍처 개요 =====
-===== 사용자 인터페이스 =====
+===== 2. 사용자 인터페이스 =====
-  * 편집기 툴바에 두 개의 AI 버튼 추가
+  * **편집기 툴바 기능**: DokuWiki 편집기 툴바에 두 개의 전용 AI 버튼을 추가하여 사용자 접근성을 높였습니다.
-  * 반응형 디자인으로 모바일 지원
+    *   파란색 버튼: 전체 편집기 내용을 기반으로 새로운 초안을 생성합니다.
-  * 색상 구분: 파란색(초안 생성), 녹색(텍스트 수정)
+    *   녹색 버튼: 선택된 텍스트를 사용자의 지시에 따라 수정합니다.
+  * **반응형 디자인**: 다양한 기기 (데스크톱, 태블릿, 모바일)에서 최적의 사용 경험을 제공하기 위해 반응형 웹 디자인 원칙을 적용했습니다.
+  * **시각적 색상 구분**: 기능별로 명확한 색상 구분을 통해 사용자가 각 버튼의 역할을 직관적으로 이해할 수 있도록 돕습니다.
-===== 백엔드 구조 =====
+===== 3. 백엔드 구조 =====
-  * ''action.php'' - 메인 플러그인 클래스
+  * **메인 플러그인 클래스 (''action.php'')**: 모든 DokuWiki 이벤트 처리와 핵심 로직을 담당하는 플러그인의 중심 파일입니다. 사용자 요청을 처리하고 Gemini API와 통신합니다.
-  * AJAX 이벤트 핸들러 등록
+  * **AJAX 이벤트 핸들러 등록**: 비동기 통신을 위해 DokuWiki의 AJAX 시스템에 사용자 인터페이스에서 발생하는 특정 이벤트를 처리하는 핸들러를 등록합니다.
-  * API 키 관리 및 보안
+  * **API 키 관리 및 보안**: Gemini API 키는 DokuWiki의 보안 설정 관리자를 통해 안전하게 저장 및 관리되며, 하드코딩을 방지하여 보안 취약점을 최소화합니다.
-  * 사용량 제한 및 모니터링
+  * **사용량 제한 및 모니터링**: 과도한 API 호출을 방지하고 비용을 효율적으로 관리하기 위해 호출 횟수를 모니터링하고 제한하는 로직이 구현되어 있습니다.
-===== 프론트엔드 구조 =====
+===== 4. 프론트엔드 구조 =====
-  * ''script.js'' - 사용자 인터페이스 로직
+  * **사용자 인터페이스 로직 (''script.js'')**: DokuWiki 편집기와 상호작용하며, 사용자의 텍스트 선택, 버튼 클릭 등 모든 UI 관련 동작을 처리합니다.
-  * 텍스트 선택 및 편집기 조작
+  * **텍스트 선택 및 편집기 조작**: 사용자가 DokuWiki 편집기에서 텍스트를 선택하거나 수정할 때, 해당 텍스트를 가져오고 AI 응답을 편집기에 다시 삽입하는 기능을 수행합니다.
-  * AJAX 통신 및 오류 처리
+  * **AJAX 통신 및 오류 처리**: 백엔드와의 비동기 통신을 담당하며, 네트워크 문제나 API 오류 발생 시 사용자에게 적절한 피드백을 제공합니다.
-  * 사용자 피드백 제공
+  * **사용자 피드백 제공**: 로딩 스피너, 성공/실패 메시지 등 시각적인 피드백을 통해 사용자가 현재 AI 작업의 상태를 명확히 알 수 있도록 합니다.
-===== 핵심 기능 =====
+===== 5. 핵심 기능 =====
-==== AI 초안 생성 TEMP_FIVE
+----
+==== 1) AI 초안 생성 ====
-  * 전체 편집기 내용을 기반으로 초안 생성
+  * **전체 편집기 내용 기반**: 현재 DokuWiki 편집기에 작성된 모든 내용을 문맥으로 활용하여, 사용자가 의도하는 바에 맞는 상세하고 일관성 있는 초안을 생성합니다. 이는 긴 문서 작성 시 매우 유용합니다.
-  * DokuWiki 문법 규칙 엄격 준수
+  * **DokuWiki 문법 규칙 엄격 준수**: 생성되는 모든 텍스트는 DokuWiki의 표준 문법 규칙(예: 제목, 목록, 링크, 강조 등)을 철저히 준수하여 별도의 수정 없이 바로 사용할 수 있도록 합니다.
-  * 상세하고 구조적인 문서 생성
+  * **상세하고 구조적인 문서 생성**: 단순히 텍스트를 나열하는 것을 넘어, 적절한 제목, 소제목, 목록 등을 활용하여 논리적이고 가독성 높은 문서 구조를 자동으로 생성합니다.
-  * 한국어 출력 보장
+  * **한국어 출력 보장**: 다국어 지원 환경에서 특히 중요하며, AI가 생성하는 모든 내용이 정확하고 자연스러운 한국어로 제공되도록 최적화되어 있습니다.
-TEMP_FIVE AI 텍스트 수정 ====
+----
+==== 2) AI 텍스트 수정 ====
-  * 선택된 텍스트만 수정
+  * **선택된 텍스트만 수정**: 사용자가 편집기에서 특정 부분을 드래그하여 선택하면, AI는 해당 선택 영역만을 대상으로 수정 작업을 수행하여 정교한 편집이 가능합니다.
-  * 사용자 지시사항 기반 수정
+  * **사용자 지시사항 기반 수정**: "더 간결하게", "전문적인 어조로 변경", "예시 추가" 등 사용자의 구체적인 지시사항을 받아들여 텍스트를 맞춤형으로 수정합니다.
-  * 원본 DokuWiki 문법 보존
+  * **원본 DokuWiki 문법 보존**: 수정 과정에서도 기존 DokuWiki 문법(예: 볼드체, 이탤릭체, 내부 링크 등)을 손상시키지 않고 유지하여 문서의 무결성을 보장합니다.
-  * 실시간 편집기 업데이트
+  * **실시간 편집기 업데이트**: AJAX 통신을 통해 AI 응답을 실시간으로 DokuWiki 편집기에 반영하여 사용자가 즉각적으로 결과를 확인하고 추가 작업을 진행할 수 있습니다.
-===== API 설정 및 보안 =====
+===== 6. API 설정 및 보안 =====
-==== API 키 관리 TEMP_FIVE
+----
+==== 1) API 키 관리 ====
-  * DokuWiki 설정 관리자를 통한 안전한 키 저장
+  * **DokuWiki 설정 관리자를 통한 안전한 키 저장**: API 키는 DokuWiki의 관리자 설정 페이지를 통해 입력되며, 시스템 파일에 하드코딩되지 않고 안전하게 암호화되어 저장됩니다. 이는 보안 취약점을 줄이고 유지보수를 용이하게 합니다.
-  * 하드코딩 방지
+  * **하드코딩 방지**: 소스 코드 내에 민감한 API 키를 직접 포함하지 않음으로써, 코드 유출 시 발생할 수 있는 보안 사고를 미연에 방지합니다.
-  * 관리자 권한으로만 접근 가능
+  * **관리자 권한으로만 접근 가능**: API 키 설정 및 변경은 DokuWiki 관리자 권한을 가진 사용자에게만 허용되어, 무단 접근 및 변경을 막습니다.
-TEMP_FIVE 사용량 제한 ====
+----
+==== 2) 사용량 제한 ====
-  * 분당 10회 호출 제한
+  * **분당 10회 호출 제한**: 짧은 시간 내 과도한 API 요청이 발생하는 것을 방지하여, 서비스 부하를 줄이고 갑작스러운 비용 증가를 막습니다.
-  * 일일 500회 호출 제한
+  * **일일 500회 호출 제한**: 하루 동안의 총 호출 횟수를 제한하여, 장기적인 관점에서 API 사용 비용을 효율적으로 관리하고 오남용을 방지합니다.
-  * 파일 기반 사용량 추적
+  * **파일 기반 사용량 추적**: 각 사용자의 API 호출 기록은 서버의 특정 로그 파일에 저장되어 실시간으로 추적되며, 이를 통해 사용량 제한을 적용합니다.
-  * 자동 제한 및 사용자 알림
+  * **자동 제한 및 사용자 알림**: 설정된 제한을 초과할 경우, API 호출이 자동으로 차단되며 사용자에게는 친절한 알림 메시지(예: "API 사용량 제한 초과")를 통해 상황을 안내합니다.
-===== 모델 설정 =====
+===== 7. 모델 설정 =====
-==== Gemini 2.5 Flash 모델 TEMP_FIVE
+----
+==== 1) Gemini 2.5 Flash 모델 ====
-  * 최신 모델 사용으로 성능 최적화
+  * **최신 모델 사용으로 성능 최적화**: Google의 최신 Gemini 2.5 Flash 모델을 사용하여, 최적의 성능과 정확성을 제공합니다. 이는 빠른 응답 속도와 우수한 텍스트 생성 능력을 보장합니다.
-  * 1,048,576 토큰 입력 한도
+  * **1,048,576 토큰 입력 한도**: 매우 긴 DokuWiki 문서(약 32,000단어 이상)도 한 번에 처리할 수 있을 만큼 방대한 입력 토큰 한도를 제공하여, 광범위한 문맥 이해를 가능하게 합니다.
-  * 65,536 토큰 출력 한도
+  * **65,536 토큰 출력 한도**: 단일 요청으로 약 2,000단어 이상의 상세한 응답을 받을 수 있는 충분한 출력 토큰 한도를 제공하여, 포괄적인 문서 초안 생성이 가능합니다.
-  * 빠른 응답 속도
+  * **빠른 응답 속도**: Flash 모델의 최적화된 설계 덕분에, 사용자 요청에 대한 AI의 응답 속도가 매우 빨라 효율적인 작업 흐름을 지원합니다.
-TEMP_FIVE 생성 설정 ====
+----
+==== 2) 생성 설정 ====
+모델의 응답 특성을 제어하기 위한 핵심 매개변수 설정입니다.
-<code>
+<file>
 generationConfig: {
-    temperature: 0.7,        // 창의성 조절
+    temperature: 0.7,        // 창의성 조절 (0.0~1.0): 값이 높을수록 더 다양하고 창의적인 응답을 생성합니다.
-    topP: 1.0,              // 다양성 조절
+    topP: 1.0,              // 다양성 조절 (0.0~1.0): 다음 토큰으로 선택될 확률이 높은 토큰들의 누적 확률을 제한하여 응답의 다양성을 조절합니다.
-    topK: 32,               // 토큰 선택 범위
+    topK: 32,               // 토큰 선택 범위 (정수): 다음 토큰을 선택할 때 고려할 가장 높은 확률을 가진 토큰의 수를 제한합니다.
-    maxOutputTokens: 8192    // 최대 출력 길이
+    maxOutputTokens: 8192    // 최대 출력 길이 (정수): AI가 생성할 수 있는 최대 토큰 수를 지정하여 응답 길이를 제어합니다.
 }
-</code>
+</file>
-===== 프롬프트 엔지니어링 =====
+===== 8. 프롬프트 엔지니어링 =====
-==== DokuWiki 문법 규칙 TEMP_FIVE
+----
+==== 1) DokuWiki 문법 규칙 ====
-  * 제목: H3~H5 레벨만 사용
+AI가 DokuWiki 문서를 정확하게 생성하고 수정할 수 있도록 지시하는 핵심 문법 규칙입니다.
-  * 목록: 2칸 들여쓰기 필수
-  * 코드: 백틱 금지, ''인라인'', <code>블록 사용
+  * **제목**: DokuWiki의 가독성 및 일관성을 위해 [[doku>syntax#sections|섹션]]은 Level 3(`===`), Level 4(`====`), Level 5(`=====`)만 사용하도록 지시합니다. Level 6(`======`)은 최상위 문서 제목에만 사용됩니다.
-  * 구분선: ---- 4개 하이픈만 사용
+  * **목록**: 들여쓰기는 정확히 두 칸(`  *` 또는 `  -`)을 사용하여 계층 구조를 명확히 표현하도록 합니다.
+  * **코드**: 인라인 코드는 `''code''` 형식으로, 여러 줄의 코드 블록은 `<file>...</file>` 태그를 사용하도록 지시하며, 백틱(`` ` ``) 사용은 엄격히 금지합니다.
+  * **구분선**: 섹션 간의 명확한 구분을 위해 정확히 네 개의 하이픈(`----`)으로 구성된 수평선을 사용하도록 합니다.
+----
+==== 2) 초안 생성 프롬프트 ====
-TEMP_FIVE 초안 생성 프롬프트 ====
+AI에게 DokuWiki 문서 초안 생성을 지시하는 기본 프롬프트입니다. 이 프롬프트는 AI가 DokuWiki 전문가로서 포괄적이고 상세한 문서를 생성하도록 유도합니다.
-<code>
+<file>
 You are an expert assistant for DokuWiki.
 Your task is to expand this raw text into a
@@ 줄 93: / 줄 109: @@
 The draft must have an introduction, a body with
 several sections (using headlines), and a conclusion.
-</code>
+</file>
-===== 오류 처리 및 디버깅 =====
+===== 9. 오류 처리 및 디버깅 =====
-===== 일반적인 오류 ====
+----
+==== 1) 일반적인 오류 ====
-  * cURL 함수 없음: php-curl 패키지 설치 필요
+플러그인 사용 중 발생할 수 있는 일반적인 문제와 해결 방법입니다.
-  * API 키 미설정: 관리자 설정에서 키 입력
-  * 사용량 초과: 제한 메시지 표시
-  * 네트워크 오류: 연결 상태 확인
-===== 디버깅 방법 ====
+  * **cURL 함수 없음**: PHP 환경에 cURL 확장이 설치되지 않은 경우 발생합니다. `sudo apt-get install php-curl` (Debian/Ubuntu) 또는 해당 OS/PHP 버전에 맞는 명령어로 설치해야 합니다.
+  * **API 키 미설정**: DokuWiki 관리자 설정에서 Gemini API 키가 올바르게 입력되지 않은 경우입니다. ''관리'' -> ''환경 설정'' -> ''플러그인 설정''에서 키를 입력하고 저장해야 합니다.
+  * **사용량 초과**: 설정된 API 호출 제한(분당/일일)을 초과한 경우입니다. 잠시 기다리거나, API 할당량을 확인하고 필요시 증량을 고려해야 합니다.
+  * **네트워크 오류**: DokuWiki 서버가 Google Gemini API 서버와 통신할 수 없는 경우 발생합니다. 서버의 인터넷 연결 상태, 방화벽 설정 등을 확인해야 합니다.
-  * 브라우저 개발자 도구에서 네트워크 탭 확인
+----
-  * DokuWiki 오류 로그 확인
+==== 2) 디버깅 방법 ====
-  * API 응답 원본 확인 (임시 디버그 모드)
-===== 성능 최적화 =====
+플러그인 문제 발생 시 원인을 파악하기 위한 디버깅 절차입니다.
-  * 비동기 AJAX 호출로 UI 블로킹 방지
+  * **브라우저 개발자 도구 확인**: 웹 브라우저의 개발자 도구(F12)를 열어 ''네트워크'' 탭에서 AI 요청 및 응답의 상태 코드, 페이로드 등을 확인하여 통신 문제를 파악합니다.
-  * 사용량 제한으로 API 비용 절약
+  * **DokuWiki 오류 로그 확인**: DokuWiki의 `data/log/debug.log` 파일에 기록되는 오류 메시지를 확인하여 백엔드에서 발생하는 PHP 오류나 플러그인 내부 오류를 분석합니다.
-  * 반응형 디자인으로 다양한 기기 지원
+  * **API 응답 원본 확인 (임시 디버그 모드)**: 플러그인 설정에 임시 디버그 모드를 활성화하여 Gemini API로부터 받은 원본 응답을 로그에 출력하도록 설정할 수 있습니다. 이를 통해 API의 실제 응답 내용을 직접 확인하여 문제를 진단합니다.
-  * 캐시 활용으로 서버 부하 감소
+===== 10. 성능 최적화 =====
+  * **비동기 AJAX 호출**: AI 응답을 기다리는 동안 사용자 인터페이스가 멈추지 않도록 비동기 AJAX 호출을 사용하여 쾌적한 사용자 경험을 제공합니다.
+  * **사용량 제한**: API 호출 횟수를 제한함으로써 불필요한 비용 발생을 방지하고, API 서버에 대한 과도한 부하를 줄여 안정적인 서비스를 유지합니다.
+  * **반응형 디자인**: 다양한 화면 크기와 해상도에 자동으로 맞춰지는 반응형 디자인을 적용하여, 데스크톱부터 모바일 기기까지 모든 환경에서 일관되고 최적화된 사용성을 보장합니다.
+  * **캐시 활용**: 자주 사용하는 데이터나 API 응답 중 재사용 가능한 부분을 캐싱하여, 불필요한 API 호출을 줄이고 서버 부하를 감소시켜 전체적인 응답 속도를 향상시킵니다.
 ----
-===== 관련 링크 =====
+===== 11. 관련 링크 =====
   * [[wiki:it:wiki:development|개발 문서 메인]]
   * [[wiki:it:wiki:gemini_api_setup|Gemini API 설정]]
   * [[wiki:it:wiki:plugin_development|플러그인 개발 가이드]]
   * [[wiki:it:start|메인 페이지]]