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