Gemini API 설정 가이드

이 문서는 DokuWiki에서 Gemini API를 사용하여 AI 기반 콘텐츠 생성 및 편집 기능을 활용하기 위한 상세한 설정 방법을 안내합니다. Gemini API는 DokuWiki 문서 작업의 효율성을 크게 향상시킬 수 있습니다.

• 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 설정에 사용됩니다.

• 절대 코드에 하드코딩 금지: API 키는 절대 DokuWiki 플러그인 코드나 다른 공개될 수 있는 파일에 직접 입력하지 마십시오. 이는 심각한 보안 취약점을 초래합니다.
• DokuWiki 설정 관리자 사용: API 키는 오직 DokuWiki의 '설정 관리자'를 통해서만 입력 및 관리되어야 합니다. DokuWiki는 이 정보를 conf/local.php 파일에 안전하게 저장합니다.
• 정기적인 키 재발급: 보안 강화를 위해 주기적으로 API 키를 재발급하고, 이전 키는 폐기하는 것이 좋습니다.
• 키 유출 방지: API 키는 개인 정보와 같이 취급하여 외부에 노출되지 않도록 각별히 주의해야 합니다.

• DokuWiki 로그인: DokuWiki에 관리자 권한을 가진 계정으로 로그인합니다.
• 관리(Admin) 버튼 클릭: DokuWiki 페이지의 오른쪽 상단에 위치한 관리(Admin) 버튼을 클릭합니다.
• 설정 관리자 선택: 관리 메뉴에서 설정 관리자(Configuration Settings)를 선택하여 DokuWiki의 전반적인 설정을 변경할 수 있는 페이지로 이동합니다.

• 설정 섹션 탐색: 설정 관리자 페이지를 아래로 스크롤하여 plugin»geminidraft 섹션을 찾습니다. 이 섹션은 설치된 GeminiDraft 플러그인의 설정을 담고 있습니다.
• API 키 입력 필드: gemini_api_key 필드에 앞서 발급받아 복사해 둔 Gemini API 키를 정확하게 붙여넣습니다. 오타나 불필요한 공백이 없도록 주의하십시오.
• 설정 저장: 키 입력 후, 페이지 하단에 있는 저장(Save) 버튼을 클릭하여 변경 사항을 적용합니다. 저장하지 않으면 설정이 반영되지 않습니다.

• 확장 기능 관리자 접속: DokuWiki 관리(Admin) 메뉴에서 확장 기능 관리자(Extension Manager)를 선택합니다.
• geminidraft 플러그인 확인: '설치된 플러그인' 탭에서 geminidraft 플러그인이 목록에 있는지 확인합니다.
• 설치되지 않은 경우: 만약 geminidraft 플러그인이 설치되어 있지 않다면, '검색 및 설치' 탭에서 'geminidraft'를 검색하여 설치를 진행해야 합니다. 플러그인이 정상적으로 설치되면 자동으로 인식됩니다.

• 편집 페이지로 이동: 임의의 DokuWiki 문서를 선택하거나 새로 생성하여 편집 페이지로 이동합니다.
• AI 초안 생성 버튼 확인: 편집기 툴바(보통 텍스트 편집 영역 상단)에 파란색 AI 초안 생성 버튼이 나타나는지 확인합니다. 이 버튼은 새로운 콘텐츠를 생성할 때 사용됩니다.
• AI 수정 버튼 확인: 녹색 AI 수정 버튼 또한 툴바에 나타나는지 확인합니다. 이 버튼은 기존 텍스트를 수정하거나 개선할 때 사용됩니다.

• 초안 내용 입력: DokuWiki 편집기에 AI가 초안을 만들고 싶은 내용의 핵심 키워드나 주제를 최소 15자 이상 입력합니다. 구체적인 지시사항을 포함할수록 더 정확하고 풍부한 초안을 얻을 수 있습니다.
• 초안 생성 버튼 클릭: 파란색 AI 초안 생성 버튼을 클릭합니다.
• 결과 확인 및 수정: AI가 입력된 내용을 바탕으로 상세한 DokuWiki 문서 형식의 초안을 생성하여 편집기에 삽입합니다. 생성된 내용을 검토하고 필요한 경우 추가적으로 수정하거나 보완합니다.

• 수정할 텍스트 선택: DokuWiki 문서 내에서 AI의 도움을 받아 수정하고 싶은 텍스트 부분을 마우스로 드래그하여 선택합니다.
• AI 수정 버튼 클릭: 녹색 AI 수정 버튼을 클릭합니다.
• 수정 지시사항 입력: 팝업창에 나타나는 입력 필드에 AI에게 원하는 수정 지시사항을 구체적으로 입력합니다.
  • 예시:
    • 더 전문적인 어조로 바꿔줘
    • 간결하게 요약해줘
    • 쉬운 말로 풀어 설명해줘
    • 문어체로 변경하고 핵심 정보를 추가해줘
• 수정된 내용 확인: AI가 지시사항에 따라 선택된 텍스트를 수정하여 교체합니다. 결과를 확인하고 만족스럽지 않다면 다시 수정 지시를 내릴 수 있습니다.

Gemini API는 Google의 무료 사용량 정책을 따르며, 다음과 같은 제한이 적용됩니다:

• 분당 호출 제한: 분당 최대 10회 API 호출이 가능합니다.
• 일일 호출 제한: 일일 최대 500회 API 호출이 가능합니다.
• 기능 자동 차단: 이러한 제한에 도달하면 Gemini API 기능이 자동으로 일시적으로 차단되며, 다음 사용 가능 시간까지 대기해야 합니다.

DokuWiki 플러그인은 사용량 제한을 추적하기 위해 특정 파일을 사용합니다.

• 일일 사용량 로그: data/cache/gemini_daily_limit.txt 파일에서 현재까지의 일일 사용량 정보를 확인할 수 있습니다.
• 분당 사용량 로그: data/cache/gemini_minute_limit.log 파일에서 최근 분당 호출 기록을 확인할 수 있습니다.
• 로그 파일 내용: 이 파일들의 내용을 통해 현재 사용량을 파악하고, 제한 도달 여부를 예측할 수 있습니다.

이 오류는 서버에 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의 경우

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 플러그인 설정에 프록시 정보를 추가해야 할 수 있습니다.

AI로부터 더 유용하고 정확한 결과물을 얻기 위해서는 '프롬프트 엔지니어링'이 중요합니다.

• 구체적이고 명확한 지시사항: AI에게 무엇을 원하는지 모호함 없이 구체적으로 지시해야 합니다.
  • 예시: “문서 요약” 대신 “이 문서를 3문단으로 요약하고, 핵심 키워드를 볼드체로 표시해줘.”
• 원하는 결과물의 형식 명시: 목록, 표, 특정 DokuWiki 구문 등 원하는 출력 형식을 명확히 알려줍니다.
• 페르소나 지정: AI가 특정 역할(예: 전문 작가, 기술 블로거)을 수행하여 응답하도록 지시할 수 있습니다.
• 예시 또는 참고 자료 제공: AI가 참고할 만한 예시 텍스트나 관련 문서를 제공하면 이해도를 높일 수 있습니다.
• 제약 조건 명시: 길이 제한, 특정 용어 사용 금지 등 AI의 응답에 대한 제약 조건을 명시합니다.

무료 사용량 제한 내에서 효율적으로 Gemini API를 활용하는 방법입니다.

• 불필요한 호출 최소화: 동일한 내용에 대해 반복적으로 AI를 호출하기보다, 한 번의 호출로 최대한의 결과를 얻도록 노력합니다.
• 결과물 재사용: AI가 생성하거나 수정한 내용을 필요하다면 다른 문서에서도 재사용하여 중복 작업을 방지합니다.
• 정기적인 사용량 모니터링: '5. 사용량 관리' 섹션에서 설명된 로그 파일을 주기적으로 확인하여 현재 사용량을 파악하고, 제한 도달 전에 사용 계획을 조정합니다.

• 개발 문서 메인 - DokuWiki 개발 관련 주요 문서입니다.
• Gemini API 연동 개발 - Gemini API 연동의 기술적인 측면을 다룹니다.
• 오류 처리 및 디버깅 - DokuWiki 사용 중 발생할 수 있는 오류에 대한 일반적인 해결책입니다.
• 메인 페이지 - DokuWiki의 시작 페이지로 돌아갑니다.
• DokuWiki GeminiDraft 플러그인 페이지 - GeminiDraft 플러그인의 공식 DokuWiki 페이지입니다.
• Google Gemini API 공식 문서 - Google Gemini API에 대한 개발자 공식 문서입니다.