선택적 AI 제공자
AI 제공자 없이도 페이지 작성, 자료 정리, 검색, 변경 검토, 질문 기능의 근거 모음을 사용할 수 있습니다. 선택적 제공자는 각각의 기능을 추가하며 위키 전체를 자동 작성하거나 모든 답변을 정답으로 만들지는 않습니다.
외부 서비스의 제공 여부와 요금은 dtxWiki와 별개입니다. 제공자를 켜기 전에 해당 서비스의 현재 이용 조건과 API 요금을 확인하세요.
실선은 기본 근거 응답이고, 점선은 운영자가 별도로 모델을 켰을 때의 경로입니다. 어느 경로에서든 근거를 직접 읽어야 합니다. 모델이 답변을 작성해도 원자료의 정확성이 보장되지는 않습니다.
선택에 따른 차이
| 선택 | 추가되는 기능 | 기본값 |
|---|---|---|
| 질문 LLM 제공자 | 질문과 검색된 근거로 문장 답변 작성 | 꺼짐(none) |
| 임베딩 제공자 | 기존 검색에 숫자 벡터를 이용한 의미 검색 경로 추가 | 꺼짐(none) |
| 재순위 제공자 | 외부 순위 서비스로 검색 후보의 순서 재조정 | 꺼짐(none) |
| MCP 외부 AI 앱 | 앱이 허용된 dtxWiki 도구를 요청 | 설정 전에는 연결 없음 |
LLM은 문장을 생성합니다. 임베딩은 비슷한 내용을 비교하도록 텍스트를 숫자로 바꿉니다. 재순위 도구는 검색 후보를 다시 정렬합니다. 각각 별도 설정이며 Claude Code 등 MCP 클라이언트를 연결해도 자동으로 구성되지 않습니다.
LLM 제공자가 없으면 질문 기능은 정해진 검색 요약과 근거를 반환합니다. 제공자가 있으면 근거 안에서 답하고 출처를 표시하도록 요청합니다. 생성된 답변도 불완전하거나 틀릴 수 있으므로 출처를 직접 확인하세요.
일반 사용자 안내
서버 운영자에게 활성화 여부와 실행 위치를 확인하세요. 로컬 모델 주소와 클라우드 API는 데이터를 보내는 대상이 다릅니다. 조직에서 허용하지 않은 제공자에게 기밀 자료를 보내지 마세요.
질문에 문장 답변 대신 근거 요약이 보이면 제공자가 꺼져 있거나 사용할 수 없는 상태일 수 있습니다. 대체 결과에서도 근거는 확인할 수 있습니다. llm_provider_unavailable, llm_composer_failed는 설정·답변 작성 실패를 뜻합니다. 자격 증명 없이 경고 문구만 운영자에게 전달하세요.
내 AI 클라이언트는 AI 앱 연결, 일반 검색과 질문은 검색과 질문을 참고하세요.
질문 제공자 켜기: 운영자 절차
이 소스는 다음 LLM 선택을 지원합니다.
DTXWIKI_LLM_PROVIDER | 필요한 비밀값 |
|---|---|
none | 없음 |
openai | DTXWIKI_OPENAI_API_KEY |
anthropic | DTXWIKI_ANTHROPIC_API_KEY |
- 제공자의 데이터 처리·API 요금을 검토하고 승인된 API 키를 준비합니다. 채팅 앱 구독만으로 API 자격 증명이 제공된다고 가정하지 마세요.
- 보호된 실행 설정이나 승인된 비밀 관리 수단에 키를 보관합니다. systemd 기본 설정은
/etc/dtxwiki/dtxwiki.env입니다. 명령 이력·공개 예제·화면 캡처에 키를 남기지 않습니다. - 제공자 선택을 설정하고 앱·작업자를 재시작해 동일한 환경을 읽게 합니다. systemd에서는 비밀값이 아닌 선택 설정을
sudo dtxwiki config set DTXWIKI_LLM_PROVIDER=openai로 바꾸고sudo systemctl restart dtxwiki dtxwiki-worker로 적용할 수 있습니다. - 알고 있는 발행된 테스트 페이지에 대해 간단한 질문을 합니다. 올바른 근거를 인용하고 제공자 경고가 없는지 확인합니다.
앱은 질문과 검색된 근거를 제공자에게 보냅니다. 이 답변을 만들기 위해 워크스페이스 전체를 보낼 필요는 없습니다. 허용할 자료는 개인정보와 안전한 공유를 참고하세요.
로컬 설치는 앱·별도 작업자 터미널에 같은 환경을 적용한 뒤 실행합니다. Docker는 검토한 Compose 설정·override로 해당 서비스의 실행 환경에 전달합니다. 호스트 shell이나 .env에만 추가한 변수는 Compose가 참조하지 않으면 컨테이너에 전달되지 않습니다.
의미 검색 설정: 운영자 절차
실제 제공자 등록부는 none, deterministic, openai_compatible을 받습니다. deterministic은 오프라인 처리 점검용 해시 방식이며 학습된 의미 검색 모델이 아닙니다.
이미 실행 중인 OpenAI 호환 임베딩 endpoint를 사용하려면 다음을 설정합니다.
| 설정 | 용도 |
|---|---|
DTXWIKI_EMBEDDING_PROVIDER=openai_compatible | endpoint 연결 방식 선택 |
DTXWIKI_EMBEDDING_BASE_URL | 보통 /v1을 포함하는 기본 주소 |
DTXWIKI_EMBEDDING_MODEL | 해당 endpoint가 제공하는 모델 |
DTXWIKI_EMBEDDING_DIM | 모델이 반환하는 벡터 크기 |
DTXWIKI_EMBEDDING_API_KEY | 인증이 필요한 endpoint의 API 키 |
dtxWiki는 모델 서버에 연결하며 모델 서버를 설치·다운로드·운영해 주지 않습니다. 내 노트북에서만이 아닌 앱과 작업자에서도 주소에 접근할 수 있어야 합니다. 로컬 endpoint를 사용하면 운영하는 인프라 안에서 해당 처리를 수행할 수 있습니다.
보호된 환경을 설정한 뒤 색인을 재작성하기 전에 검사합니다.
# systemd 설치: 래퍼가 운영 설정을 읽음
sudo dtxwiki embedding doctor
짧은 테스트 문구로 endpoint·벡터 크기·응답 시간을 확인합니다. 오류를 먼저 해결하세요. 모델이나 크기를 바꾸면 작업 시간을 정해 다음을 실행합니다.
sudo dtxwiki reindex
현재 설정으로 색인을 재작성합니다. 모든 워크스페이스 자료를 처리하고 임베딩 서비스에 요청할 수 있으므로 시간·API 비용을 고려하세요. 로컬은 같은 환경에서 sudo 없이 실행하고 Docker는 설정된 app 서비스 안에서 실행합니다.
선택적 재순위 등록부는 none 또는 api를 받으며 DTXWIKI_RERANK_BASE_URL, DTXWIKI_RERANK_MODEL, 필요한 경우 DTXWIKI_RERANK_API_KEY를 사용합니다. 외부 서비스를 이용하므로 기본 검색·임베딩 경로가 정상 동작한 뒤 검토하세요.
제공자가 실패할 때
설정한 답변기를 만들거나 사용할 수 없으면 질문 기능은 근거 모음으로 대체합니다. 선택적 의미 검색 제공자가 없어도 키워드·탐색 결과를 유지할 수 있습니다. 대체 결과를 제공자 호출 성공으로 해석하지 말고 경고와 해당 진단을 확인하세요.
벡터 크기 불일치를 해결하려고 숫자를 추측하지 마세요. 모델 endpoint의 반환 크기를 확인해 설정을 일치시키고 색인을 재작성합니다. 서버·작업자 문제는 문제 해결을 참고하세요.
버전 근거: 실제 제공자 등록부, 질문 근거·대체 동작, 임베딩 진단, 색인 재작성 명령.