문제 해결
대부분의 Notemd 문제는 네 가지 범주로 나뉩니다: API 관련 문제, 네트워크 연결 문제, 인증 오류(401/403), 그리고 요청 제한(429)입니다. 내장된 연결 테스트 및 진단 패널을 통해 근본 원인을 빠르게 파악할 수 있습니다. 이 페이지에서는 모든 일반적인 오류 메시지, 그 원인, 그리고 해결 방법을 다룹니다. 여기에 명시되지 않은 문제가 있을 경우, 진단 결과와 함께 GitHub Issues에 보고해 주십시오.
이것은 Obsidian AI 지식 관리 가이드의 일부입니다.
개요
Notemd는 외부 서비스인 -- LLM 제공업체들과 검색 API 서비스들에 의존하기 때문에 대부분의 문제는 플러그인 자체가 아닌 외부에서 발생합니다. 설정에 있는 진단 패널을 통해 요청 URL, 응답 상태, 오류 내용을 포함한 마지막 API 호출에 대한 구조화된 정보를 확인할 수 있습니다. 더 깊이 조사하기 전에 항상 먼저 이 패널을 확인해 보세요.
작동 원리: 진단
연결 테스트
모든 공급업체 설정 섹션에는 "Test Connection" 버튼이 있습니다. 이 버튼을 클릭하면 최소한의 API 요청(일반적으로 모델 목록 또는 간단한 완성 결과)이 전송되고, 성공 여부나 특정 HTTP 오류가 보고됩니다. 이 방법은 API 키와 기본 URL 값이 올바른지 확인하는 가장 빠른 수단입니다.
진단 패널
설정 --> Notemd --> 진단에는 다음과 같이 표시됩니다:
| 필드 | 콘텐츠 |
|---|---|
| 마지막 공급자 | 마지막으로 호출된 제공업체는 무엇인가요? |
| 최신 모델 | 마지막으로 호출된 모델은 무엇인가요? |
| 마지막 상태 | HTTP 상태 코드 또는 전송 오류 |
| 마지막 오류 | API에서 나온 원시 오류 메시지 |
| 마지막 요청 URL | 마지막 요청의 전체 내용 URL (API 키는 익명 처리됨) |
| 마지막 응답 본문 | 응답 본문이 잘림 (처음 500자) |
GitHub에 문제를 보고할 때 전체 진단 결과를 복사하세요.
일반적인 오류
API 키가 유효하지 않거나 누락되었습니다.
증상: HTTP 401 오류 또는 "잘못된 API 키가 제공되었습니다"
원인: API 키가 누락되었거나, 공백이 포함되어 있거나, 다른 제공업체에 속해 있습니다.
수정:
- 키에 앞뒤 공백이 없는지 확인하세요.
- 선택한 제공업체와 키가 일치하는지 확인하십시오(OpenAI 키는 Anthropic와 함께 사용할 수 없습니다).
- 귀하의 계정에 크레딧이 있거나 활성 구독이 되어 있는지 확인하세요.
- **"Test Connection"**을 클릭하여 확인하세요
네트워크/연결 오류
증상: ERR_CONNECTION_REFUSED, ERR_TIMED_OUT, Socket hang up, Network request failed
원인: 귀하의 컴퓨터에서 API 엔드포인트에 연결할 수 없습니다.
수정:
- 인터넷 연결을 확인해 주세요.
- 프록시나 방화벽 뒤에 있는 경우 API 도메인이 차단되지 않았는지 확인하십시오.
- Ollama에 대해:
ollama serve이 실행 중인지 확인하세요 (ollama list는 모델들을 반환해야 합니다) - LMStudio에 대해:
localhost:1234에서 서버가 실행 중인지 확인하십시오. - 다른 전송 방식을 시도해 보세요. 모바일 사용자는
requestUrl전송 방식이 활성화되어 있는지 확인해야 합니다. - 일시적 오류 시 자동 재시도를 위해
enableStableApiCall을 활성화하세요
403 금지됨
증상: HTTP 403
원인: 귀하의 API 키는 유효하지만 요청된 리소스에 대한 권한이 없습니다.
수정:
- 일부 모델은 특별한 접근 권한이 필요합니다(예: Azure를 통한 GPT-4의 경우 배포 이름이 필요함).
- 일부 제공업체는 플랜 등급에 따라 모델을 제한합니다. 귀하의 계정을 확인해 보세요.
- 지역별 제한이 적용될 수 있습니다(일부 중국 서비스 제공업체는 국제 IP를 차단하고, 그 반대의 경우도 마찬가지입니다).
- 모델 이름이 올바르게 표기되었는지 확인하세요(예: 미니 모델만 사용이 허용된 경우
gpt-4o가 아닌gpt-4o-mini가 되어서는 안 됨).
속도 제한 (429)
증상: HTTP 429 또는 “요청 속도 제한 초과”
원인: 짧은 시간 내에 너무 많은 요청이 발생함.
수정:
batchConcurrency를1또는2로 줄이세요.- 다시 시도하기 전에 몇 분 정도 기다려 주세요.
- 귀하의 플랜 등급에 해당하는 제공업체의 요금 제한 관련 문서를 확인해 주세요.
- 백오프를 사용한 자동 재시도를 위해
enableStableApiCall을 활성화하세요 - 더 높은 한도를 제공하는 서비스 제공업체로 전환하는 것을 고려해 보세요(DeepSeek, Ollama).
모델을 찾을 수 없습니다.
증상: "모델을 찾을 수 없음" 또는 HTTP 404
원인: 선택한 제공자에 해당 모델 이름이 존재하지 않습니다.
수정:
- **"모델 목록 가져오기"**를 클릭하여 제공업체에서 사용할 수 있는 모든 모델을 확인하세요.
- 일부 모델 이름은 시간이 지남에 따라 변경될 수 있습니다. 제공업체의 문서에서 현재 이름을 확인하십시오.
- Ollama의 경우: 끌어온 모델들을 보려면
ollama list를 실행하세요. 다운로드된 모델만 사용할 수 있습니다.
링크 없음 / 개념 생성 안 됨
증상: 명령어는 실행되지만 아무런 출력도 나오지 않습니다.
원인: LLM에서 빈 값이거나 해석할 수 없는 응답이 반환되었습니다.
수정:
- 실제 LLM 응답을 확인하기 위해 진단 패널을 살펴보세요.
- 더 강력한 모델을 사용해 보세요(일부 소형 모델들은 구조화된 출력을 처리하는 데 어려움이 있습니다).
- 이 메모에 충분한 내용이 포함되도록 하세요(50단어 이상).
- 충돌하는 지시사항이 있는지 사용자 정의 프롬프트를 검토해 주세요.
- 동의어 억제 기능을 일시적으로 비활성화하여 과도하게 필터링되는지 확인해 보세요.
Doubao 엔드포인트 ID가 누락되었습니다.
증상: ByteDance Doubao 프로바이더를 사용할 때 오류 발생
원인: Doubao은 모델 이름 대신 Ark 엔드포인트 ID(형식: ep-xxxxxxxx-xxxx-xxxx)가 필요합니다.
수정 방법: Volcengine 콘솔에서 가져온 실제 엔드포인트 ID로 기본 플레이스홀더 모델을 대체하십시오.
구성 설정
| 진단 설정 | 위치 | 목적 |
|---|---|---|
| 연결 테스트 | 설정 --> 공급자 섹션 | API 키와 연결성을 확인하세요. |
| 모델 목록 가져오기 | 설정 --> 공급자 섹션 | 어떤 모델들에 접근할 수 있는지 확인하세요. |
enableStableApiCall | 설정 --> 고급 | 백오프와 함께 재시도를 활성화합니다. |
batchConcurrency | 설정 --> 일괄 처리 | 속도 제한을 피하기 위해 병렬 처리를 제어하세요 |
문제를 신고하는 방법
위에 언급된 내용으로 해결되지 않는 문제라면:
- 설정 --> Notemd --> 진단을 엽니다.
- 전체 진단 결과를 복사하세요
- github.com/Jacobinwwey/obsidian-NotEMD/issues에 GitHub 이슈를 생성하세요.
- 포함할 내용: Obsidian 버전, Notemd 버전, 제공업체, 모델, 진단 결과, 재현 방법
- 공유된 모든 로그에서 API 키를 삭제하세요.
다음 단계
- LLM 공급자 -- 전체 공급자 설정 참조
- 배치 처리 -- 대규모 작업을 위한 동시성 및 재시도 설정
- Custom Prompts -- 프롬프트를 조정하여 예기치 않은 LLM 동작을 수정합니다