[08-Documenter] #311 설계서 Approved + reference + 사용자 가이드 FAQ

- docs/design/311-llm-warmup/ 3파일 상태 Draft → Approved (v0.4.1)
- docs/reference/311-llm-warmup.md 신규 (상태 머신, API, UI binding,
  마이크로카피, 테스트)
- docs/guides/ai-chat-using.md 헤더 + FAQ 2건 추가 (warmup 인지/회복)

Refs #311
This commit is contained in:
2026-06-15 13:25:38 +09:00
parent 121108f63c
commit 41457ab96e
5 changed files with 115 additions and 6 deletions

View File

@@ -1,6 +1,6 @@
# AI 코치와 대화하기 (사용자 가이드)
> 적용 버전: **v0.4.0 이상** · Redmine #260 · 관련 레퍼런스: [docs/reference/260-in-app-tool-calling.md](../reference/260-in-app-tool-calling.md)
> 적용 버전: **v0.4.0 이상** (warm-up 은 **v0.4.1+**) · Redmine #260 / #311 · 관련 레퍼런스: [도구 호출](../reference/260-in-app-tool-calling.md) · [Warm-up](../reference/311-llm-warmup.md)
>
> 본 가이드는 v0.3.0 의 [AI 도움 켜기·끄기](ai-help-onboarding.md) 가 끝났다는 전제에서 시작합니다. 모델이 단말에 준비되어 있어야 합니다.
@@ -52,6 +52,12 @@ A. 4 회를 넘기면 자동으로 멈추고 "도구 호출 루프가 너무 길
**Q. 응답이 너무 느린 것 같아요.**
A. 단말 모델이라 1턴 평균 2~5초가 정상입니다. AI 가 도구를 호출하면 round trip 이 한 번 더 들어가 6~10초가 될 수 있어요.
**Q. ChatScreen 진입 시 입력창에 "AI 준비 중…" 이 떠요.**
A. v0.4.1 부터 모델을 백그라운드로 미리 시동합니다 (warm-up). 첫 진입 시 한 번만 보이고 평균 2~8초 안에 사라집니다. 그동안 메시지를 미리 타이핑해도 되고, send 버튼만 비활성 상태로 기다립니다. 다시 진입하면 즉시 사용 가능합니다.
**Q. "AI 모델 파일을 찾을 수 없어요." / "AI 를 시작하지 못했어요." 가 떠요.**
A. 파일을 못 찾는 경우는 [설정으로 가기] 로 이동해 재다운로드, 일시적 시작 실패는 [다시 시도] 로 회복합니다. 설정에서 다운로드를 완료하고 돌아오면 자동으로 다시 시도합니다.
**Q. 도구 결과가 잘렸어요.**
A. 모델 컨텍스트 보호를 위해 도구 결과는 2KB 로 제한됩니다. 잘림이 발생하면 AI 가 자동으로 단건 조회 (`프로토콜 상세`) 도구를 다시 부르도록 안내됩니다.