차이

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

--- wiki:it:wiki:gemini_api_setup [2025/08/01 12:05] – [API 키 발급] syjang0803
+++ wiki:it:wiki:gemini_api_setup [2025/08/01 12:40] (현재) – syjang0803
@@ 줄 1: / 줄 1: @@
 ====== Gemini API 설정 가이드 ======
-이 문서는 DokuWiki에서 Gemini API를 사용하기 위한 설정 방법을 상세히 설명합니다.
+이 문서는 DokuWiki에서 Gemini API를 사용하여 AI 기반 콘텐츠 생성 및 편집 기능을 활용하기 위한 상세한 설정 방법을 안내합니다. Gemini API는 DokuWiki 문서 작업의 효율성을 크게 향상시킬 수 있습니다.
-===== API 키 발급 =====
+===== 1. API 키 발급 =====
-==== Google AI Studio 접속 ====
+----
+==== 1) Google AI Studio 접속 및 키 생성 ====
-  * https://aistudio.google.com/ 에 접속
+  * **Google AI Studio 접속**: 웹 브라우저를 열고 다음 주소로 이동합니다: ''https://aistudio.google.com/''
-  * Google 계정으로 로그인
+  * **Google 계정으로 로그인**: 개인 또는 조직의 Google 계정으로 로그인합니다.
-  * Get API key 버튼 클릭
+  * **API 키 생성 시작**: 페이지 중앙 또는 좌측 메뉴에서 ''Get API key'' 버튼을 클릭합니다.
-  * 새 API 키 생성 및 복사
+  * **새 API 키 생성**: 'Create API key in new project' 또는 'Create API key in existing project'를 선택하여 새로운 API 키를 생성합니다.
+  * **생성된 키 복사**: 화면에 표시되는 API 키를 즉시 복사하여 안전한 곳에 임시로 보관합니다. 이 키는 DokuWiki 설정에 사용됩니다.
-==== API 키 보안 ====
+----
+==== 2) API 키 보안 관리 ====
-  * API 키는 절대 코드에 하드코딩하지 마세요
+  * **절대 코드에 하드코딩 금지**: API 키는 절대 DokuWiki 플러그인 코드나 다른 공개될 수 있는 파일에 직접 입력하지 마십시오. 이는 심각한 보안 취약점을 초래합니다.
-  * DokuWiki 설정 관리자에서만 입력
+  * **DokuWiki 설정 관리자 사용**: API 키는 오직 DokuWiki의 '설정 관리자'를 통해서만 입력 및 관리되어야 합니다. DokuWiki는 이 정보를 ''conf/local.php'' 파일에 안전하게 저장합니다.
-  * 정기적으로 키를 재발급하여 보안 강화
+  * **정기적인 키 재발급**: 보안 강화를 위해 주기적으로 API 키를 재발급하고, 이전 키는 폐기하는 것이 좋습니다.
+  * **키 유출 방지**: API 키는 개인 정보와 같이 취급하여 외부에 노출되지 않도록 각별히 주의해야 합니다.
-===== DokuWiki 설정 =====
+===== 2. DokuWiki 설정 =====
-==== 관리자 페이지 접속 TEMP_FIVE
+----
+==== 1) 관리자 페이지 접속 ====
-  * DokuWiki에 관리자 계정으로 로그인
+  * **DokuWiki 로그인**: DokuWiki에 관리자 권한을 가진 계정으로 로그인합니다.
-  * 오른쪽 상단 ''관리(Admin)'' 버튼 클릭
+  * **관리(Admin) 버튼 클릭**: DokuWiki 페이지의 오른쪽 상단에 위치한 ''관리(Admin)'' 버튼을 클릭합니다.
-  * ''설정 관리자(Configuration Settings)'' 선택
+  * **설정 관리자 선택**: 관리 메뉴에서 ''설정 관리자(Configuration Settings)''를 선택하여 DokuWiki의 전반적인 설정을 변경할 수 있는 페이지로 이동합니다.
-TEMP_FIVE API 키 입력 ====
+----
+==== 2) API 키 입력 및 저장 ====
-  * 페이지를 아래로 스크롤
+  * **설정 섹션 탐색**: 설정 관리자 페이지를 아래로 스크롤하여 ''plugin»geminidraft'' 섹션을 찾습니다. 이 섹션은 설치된 GeminiDraft 플러그인의 설정을 담고 있습니다.
-  * ''plugin»geminidraft'' 섹션 찾기
+  * **API 키 입력 필드**: ''gemini_api_key'' 필드에 앞서 발급받아 복사해 둔 Gemini API 키를 정확하게 붙여넣습니다. 오타나 불필요한 공백이 없도록 주의하십시오.
-  * ''gemini_api_key'' 필드에 발급받은 키 입력
+  * **설정 저장**: 키 입력 후, 페이지 하단에 있는 ''저장(Save)'' 버튼을 클릭하여 변경 사항을 적용합니다. 저장하지 않으면 설정이 반영되지 않습니다.
-  * ''저장(Save)'' 버튼 클릭
-===== 플러그인 활성화 =====
+===== 3. 플러그인 활성화 및 확인 =====
-==== 플러그인 확인 TEMP_FIVE
+----
+==== 1) 플러그인 설치 및 확인 ====
-  * ''관리(Admin)'' → ''확장 기능 관리자(Extension Manager)''
+  * **확장 기능 관리자 접속**: DokuWiki ''관리(Admin)'' 메뉴에서 ''확장 기능 관리자(Extension Manager)''를 선택합니다.
-  * ''geminidraft'' 플러그인이 설치되어 있는지 확인
+  * **''geminidraft'' 플러그인 확인**: '설치된 플러그인' 탭에서 ''geminidraft'' 플러그인이 목록에 있는지 확인합니다.
-  * 플러그인이 자동으로 인식되어야 함
+  * **설치되지 않은 경우**: 만약 ''geminidraft'' 플러그인이 설치되어 있지 않다면, '검색 및 설치' 탭에서 'geminidraft'를 검색하여 설치를 진행해야 합니다. 플러그인이 정상적으로 설치되면 자동으로 인식됩니다.
-TEMP_FIVE 기능 테스트 ====
+----
+==== 2) 기능 버튼 확인 ====
-  * 아무 문서나 편집 페이지로 이동
+  * **편집 페이지로 이동**: 임의의 DokuWiki 문서를 선택하거나 새로 생성하여 편집 페이지로 이동합니다.
-  * 편집기 툴바에 파란색 ''AI 초안 생성'' 버튼 확인
+  * **AI 초안 생성 버튼 확인**: 편집기 툴바(보통 텍스트 편집 영역 상단)에 파란색 ''AI 초안 생성'' 버튼이 나타나는지 확인합니다. 이 버튼은 새로운 콘텐츠를 생성할 때 사용됩니다.
-  * 녹색 ''AI 수정'' 버튼 확인
+  * **AI 수정 버튼 확인**: 녹색 ''AI 수정'' 버튼 또한 툴바에 나타나는지 확인합니다. 이 버튼은 기존 텍스트를 수정하거나 개선할 때 사용됩니다.
-===== 사용법 가이드 =====
+===== 4. 사용법 가이드 =====
-==== AI 초안 생성 TEMP_FIVE
+----
+==== 1) AI 초안 생성 기능 ====
-  * 편집기에 초안을 만들고 싶은 내용 입력 (15자 이상)
+  * **초안 내용 입력**: DokuWiki 편집기에 AI가 초안을 만들고 싶은 내용의 핵심 키워드나 주제를 최소 15자 이상 입력합니다. 구체적인 지시사항을 포함할수록 더 정확하고 풍부한 초안을 얻을 수 있습니다.
-  * 파란색 ''AI 초안 생성'' 버튼 클릭
+  * **초안 생성 버튼 클릭**: 파란색 ''AI 초안 생성'' 버튼을 클릭합니다.
-  * AI가 상세한 DokuWiki 문서로 확장
+  * **결과 확인 및 수정**: AI가 입력된 내용을 바탕으로 상세한 DokuWiki 문서 형식의 초안을 생성하여 편집기에 삽입합니다. 생성된 내용을 검토하고 필요한 경우 추가적으로 수정하거나 보완합니다.
-  * 결과를 확인하고 필요시 수정
-TEMP_FIVE AI 텍스트 수정 ====
+----
+==== 2) AI 텍스트 수정 기능 ====
-  * 수정하고 싶은 텍스트를 드래그하여 선택
+  * **수정할 텍스트 선택**: DokuWiki 문서 내에서 AI의 도움을 받아 수정하고 싶은 텍스트 부분을 마우스로 드래그하여 선택합니다.
-  * 녹색 ''AI 수정'' 버튼 클릭
+  * **AI 수정 버튼 클릭**: 녹색 ''AI 수정'' 버튼을 클릭합니다.
-  * 수정 지시사항 입력 (예: ''더 전문적으로 바꿔줘'')
+  * **수정 지시사항 입력**: 팝업창에 나타나는 입력 필드에 AI에게 원하는 수정 지시사항을 구체적으로 입력합니다.
-  * 선택된 텍스트가 수정된 내용으로 교체
+    *   **예시**:
+      *   ''더 전문적인 어조로 바꿔줘''
+      *   ''간결하게 요약해줘''
+      *   ''쉬운 말로 풀어 설명해줘''
+      *   ''문어체로 변경하고 핵심 정보를 추가해줘''
+  * **수정된 내용 확인**: AI가 지시사항에 따라 선택된 텍스트를 수정하여 교체합니다. 결과를 확인하고 만족스럽지 않다면 다시 수정 지시를 내릴 수 있습니다.
-===== 사용량 관리 =====
+===== 5. 사용량 관리 =====
-==== 무료 사용량 TEMP_FIVE
+----
+==== 1) Gemini API 무료 사용량 제한 ====
-  * 분당 10회 호출 제한
+Gemini API는 Google의 무료 사용량 정책을 따르며, 다음과 같은 제한이 적용됩니다:
-  * 일일 500회 호출 제한
-  * 제한 도달 시 자동으로 기능 차단
-TEMP_FIVE 사용량 확인 ====
+  * **분당 호출 제한**: 분당 최대 10회 API 호출이 가능합니다.
+  * **일일 호출 제한**: 일일 최대 500회 API 호출이 가능합니다.
+  * **기능 자동 차단**: 이러한 제한에 도달하면 Gemini API 기능이 자동으로 일시적으로 차단되며, 다음 사용 가능 시간까지 대기해야 합니다.
-  * ''data/cache/gemini_daily_limit.txt'' 파일 확인
+----
-  * ''data/cache/gemini_minute_limit.log'' 파일 확인
+==== 2) DokuWiki 내 사용량 확인 ====
-  * 파일 내용으로 현재 사용량 파악 가능
-===== 문제 해결 =====
+DokuWiki 플러그인은 사용량 제한을 추적하기 위해 특정 파일을 사용합니다.
-===== 일반적인 오류 ====
+  * **일일 사용량 로그**: ''data/cache/gemini_daily_limit.txt'' 파일에서 현재까지의 일일 사용량 정보를 확인할 수 있습니다.
+  * **분당 사용량 로그**: ''data/cache/gemini_minute_limit.log'' 파일에서 최근 분당 호출 기록을 확인할 수 있습니다.
+  * **로그 파일 내용**: 이 파일들의 내용을 통해 현재 사용량을 파악하고, 제한 도달 여부를 예측할 수 있습니다.
+===== 6. 문제 해결 =====
+----
+==== 1) 일반적인 오류 유형 및 해결책 ====
+----
+=== cURL 함수 없음 ===
-===== cURL 함수 없음 =====
+이 오류는 서버에 PHP cURL 확장이 설치되어 있지 않거나 활성화되지 않았을 때 발생합니다. cURL은 DokuWiki가 Gemini API 서버와 통신하는 데 필요한 라이브러리입니다.
-<code>
+<file>
 Error: Call to undefined function curl_init()
-</code>
+</file>
 **해결 방법:**
-<code>
+  * **PHP cURL 설치**: 서버 운영체제에 따라 다음 명령어를 사용하여 cURL 확장을 설치합니다. (예시: Ubuntu/Debian 기반 시스템)
+<file>
 sudo apt-get update
 sudo apt-get install php-curl
-sudo systemctl restart apache2
+</file>
-</code>
+  * **웹 서버 재시작**: cURL 설치 후, 변경 사항을 적용하려면 웹 서버(예: Apache, Nginx)를 재시작해야 합니다.
+<file>
+sudo systemctl restart apache2 // Apache의 경우
+sudo systemctl restart nginx // Nginx의 경우
+</file>
-===== API 키 미설정 =====
+----
+=== API 키 미설정 ===
+Gemini API 키가 DokuWiki 설정에 올바르게 입력되지 않았을 때 나타나는 오류입니다.
-<code>
+<file>
 Error: Gemini API key is not configured
-</code>
+</file>
 **해결 방법:**
-  * DokuWiki 설정 관리자에서 API 키 입력
+  * **DokuWiki 설정 관리자 확인**: '2. DokuWiki 설정' 섹션의 지침에 따라 DokuWiki 설정 관리자에서 ''gemini_api_key'' 필드에 발급받은 API 키를 정확하게 입력했는지 다시 확인합니다.
-  * 키가 올바르게 저장되었는지 확인
+  * **오타 및 공백 확인**: 키를 복사-붙여넣기 할 때 오타나 불필요한 공백이 포함되지 않았는지 주의 깊게 확인합니다.
-===== 사용량 초과 =====
+----
+=== 사용량 초과 ===
+Gemini API의 일일 또는 분당 호출 제한에 도달했을 때 발생하는 오류입니다.
-<code>
+<file>
 Error: The daily limit has been reached
-</code>
+</file>
 **해결 방법:**
-  * 다음 날까지 대기
+  * **다음 사용 가능 시간까지 대기**: 일일 제한에 도달했다면 다음 날까지 기다려야 합니다. 분당 제한이라면 몇 분 후 다시 시도합니다.
-  * 또는 사용량 로그 파일 삭제 (임시 해결)
+  * **로그 파일 삭제 (임시 해결)**: ''data/cache/gemini_daily_limit.txt'' 또는 ''data/cache/gemini_minute_limit.log'' 파일을 삭제하면 DokuWiki 플러그인의 로컬 사용량 추적 기록이 초기화됩니다. **그러나 이는 Google의 실제 API 제한을 우회하는 것이 아니므로, 곧 다시 제한에 도달할 수 있습니다.** 근본적인 해결책은 아닙니다.
-===== 네트워크 오류 =====
+----
+=== 네트워크 오류 ===
+DokuWiki 서버가 Gemini API 엔드포인트에 접속하지 못할 때 발생하는 오류입니다.
-<code>
+<file>
 Error: Failed to get a response from the Gemini API
-</code>
+</file>
 **해결 방법:**
-  * 인터넷 연결 상태 확인
+  * **인터넷 연결 상태 확인**: DokuWiki 서버의 인터넷 연결이 안정적인지 확인합니다.
-  * API 키 유효성 확인
+  * **API 키 유효성 확인**: 발급받은 API 키가 여전히 유효한지 Google AI Studio에서 확인합니다. 폐기되었거나 잘못된 키일 수 있습니다.
-  * 방화벽 설정 확인
+  * **방화벽 설정 확인**: 서버의 방화벽이 Gemini API 통신을 차단하고 있지 않은지 확인합니다. 필요한 경우 포트(일반적으로 443/HTTPS)를 열어주어야 합니다.
+  * **프록시 설정**: DokuWiki 서버가 프록시 서버를 통해 인터넷에 접속해야 하는 환경이라면, PHP cURL 설정 또는 DokuWiki 플러그인 설정에 프록시 정보를 추가해야 할 수 있습니다.
-===== 성능 최적화 =====
+===== 7. AI 활용 최적화 =====
-==== 프롬프트 개선 TEMP_FIVE
+----
+==== 1) 프롬프트 개선을 통한 결과물 향상 ====
-  * 구체적이고 명확한 지시사항 사용
+AI로부터 더 유용하고 정확한 결과물을 얻기 위해서는 '프롬프트 엔지니어링'이 중요합니다.
-  * 원하는 결과물의 형식 명시
-  * 예시나 참고 자료 제공
-TEMP_FIVE 사용량 절약 ====
+  * **구체적이고 명확한 지시사항**: AI에게 무엇을 원하는지 모호함 없이 구체적으로 지시해야 합니다.
+    *   **예시**: "문서 요약" 대신 "이 문서를 3문단으로 요약하고, 핵심 키워드를 볼드체로 표시해줘."
-  * 불필요한 호출 최소화
+  * **원하는 결과물의 형식 명시**: 목록, 표, 특정 DokuWiki 구문 등 원하는 출력 형식을 명확히 알려줍니다.
-  * 결과물을 재사용하여 중복 작업 방지
+  * **페르소나 지정**: AI가 특정 역할(예: 전문 작가, 기술 블로거)을 수행하여 응답하도록 지시할 수 있습니다.
-  * 정기적으로 사용량 모니터링
+  * **예시 또는 참고 자료 제공**: AI가 참고할 만한 예시 텍스트나 관련 문서를 제공하면 이해도를 높일 수 있습니다.
+  * **제약 조건 명시**: 길이 제한, 특정 용어 사용 금지 등 AI의 응답에 대한 제약 조건을 명시합니다.
 ----
+==== 2) 스마트한 사용량 절약 팁 ====
-===== 관련 링크 =====
+무료 사용량 제한 내에서 효율적으로 Gemini API를 활용하는 방법입니다.
-  * [[wiki:it:wiki:development|개발 문서 메인]]
-  * [[wiki:it:wiki:gemini_api_integration|Gemini API 연동 개발]]
-  * [[wiki:it:wiki:error_handling|오류 처리 및 디버깅]]
-  * [[wiki:it:start|메인 페이지]]
+  * **불필요한 호출 최소화**: 동일한 내용에 대해 반복적으로 AI를 호출하기보다, 한 번의 호출로 최대한의 결과를 얻도록 노력합니다.
+  * **결과물 재사용**: AI가 생성하거나 수정한 내용을 필요하다면 다른 문서에서도 재사용하여 중복 작업을 방지합니다.
+  * **정기적인 사용량 모니터링**: '5. 사용량 관리' 섹션에서 설명된 로그 파일을 주기적으로 확인하여 현재 사용량을 파악하고, 제한 도달 전에 사용 계획을 조정합니다.
+===== 8. 관련 링크 =====
+  * [[wiki:it:wiki:development|개발 문서 메인]] - DokuWiki 개발 관련 주요 문서입니다.
+  * [[wiki:it:wiki:gemini_api_integration|Gemini API 연동 개발]] - Gemini API 연동의 기술적인 측면을 다룹니다.
+  * [[wiki:it:wiki:error_handling|오류 처리 및 디버깅]] - DokuWiki 사용 중 발생할 수 있는 오류에 대한 일반적인 해결책입니다.
+  * [[wiki:it:start|메인 페이지]] - DokuWiki의 시작 페이지로 돌아갑니다.
+  * [[https://www.dokuwiki.org/plugin:geminidraft|DokuWiki GeminiDraft 플러그인 페이지]] - GeminiDraft 플러그인의 공식 DokuWiki 페이지입니다.
+  * [[https://ai.google.dev/gemini-api/docs/overview|Google Gemini API 공식 문서]] - Google Gemini API에 대한 개발자 공식 문서입니다.