<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Briefold</title>
    <description>The latest articles on DEV Community by Briefold (@briefold).</description>
    <link>https://dev.to/briefold</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4255277%2Fb601a2f2-c8fc-43bc-9eb1-69bd47900e98.png</url>
      <title>DEV Community: Briefold</title>
      <link>https://dev.to/briefold</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/briefold"/>
    <language>en</language>
    <item>
      <title>내 PDF 문서를 로컬 LLM에게 검색시키기 — RAG 실전 구축</title>
      <dc:creator>Briefold</dc:creator>
      <pubDate>Fri, 20 Nov 2026 08:59:11 +0000</pubDate>
      <link>https://dev.to/briefold/nae-pdf-munseoreul-rokeol-llmege-geomsaegsikigi-rag-siljeon-gucug-1fhd</link>
      <guid>https://dev.to/briefold/nae-pdf-munseoreul-rokeol-llmege-geomsaegsikigi-rag-siljeon-gucug-1fhd</guid>
      <description>&lt;h2&gt;
  
  
  목차
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;준비 조건과 전체 구조&lt;/li&gt;
&lt;li&gt;PDF 추출부터 벡터 검색까지&lt;/li&gt;
&lt;li&gt;로컬 LLM 연결과 선택 기준&lt;/li&gt;
&lt;li&gt;자주 묻는 질문&lt;/li&gt;
&lt;li&gt;결론&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  준비 조건과 전체 구조
&lt;/h2&gt;

&lt;p&gt;Python이 설치되어 있고 로컬 LLM 서버가 HTTP API를 제공한다고 가정합니다. 예를 들어 Ollama나 llama.cpp server처럼 OpenAI 호환 API를 제공하는 서버를 사용할 수 있으며, 실제 서버에 따라 주소와 모델 지정 방식을 바꿔야 합니다. PDF 파일은 &lt;code&gt;docs&lt;/code&gt; 폴더에 준비하며, 스캔 이미지 PDF는 별도 OCR(이미지에서 문자를 읽는 기술)이 필요하고 OCR 결과도 원문과 대조해 품질을 확인해야 합니다.&lt;/p&gt;

&lt;p&gt;구조는 &lt;code&gt;PDF 텍스트 추출 → 청킹 → 임베딩 생성 → 벡터 저장 → 유사도 검색 → 로컬 LLM 답변 생성&lt;/code&gt; 순서로 진행합니다. 임베딩은 문장을 숫자 벡터로 바꾸는 과정이고, RAG는 검색 결과를 LLM의 질문 문맥에 넣어 답변하게 하는 방식입니다.&lt;/p&gt;

&lt;p&gt;이 예제는 텍스트를 추출할 수 있는 PDF, paraphrase-multilingual-MiniLM-L12-v2의 128토큰 한도, OpenAI 호환 API를 제공하는 로컬 LLM 서버를 기준으로 합니다.&lt;/p&gt;

&lt;h2&gt;
  
  
  PDF 추출부터 벡터 검색까지
&lt;/h2&gt;

&lt;p&gt;먼저 PDF 페이지별 텍스트와 페이지 번호를 함께 저장합니다. 페이지 정보가 있어야 답변이 어긋날 때 원문 위치를 다시 확인할 수 있습니다.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;pip install pypdf sentence-transformers faiss-cpu requests numpy
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="n"&gt;pathlib&lt;/span&gt; &lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="nc"&gt;Path&lt;/span&gt;
&lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="n"&gt;pypdf&lt;/span&gt; &lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="nc"&gt;PdfReader&lt;/span&gt;
&lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="n"&gt;sentence_transformers&lt;/span&gt; &lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="nc"&gt;SentenceTransformer&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;faiss&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;json&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;numpy&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="n"&gt;np&lt;/span&gt;

&lt;span class="n"&gt;model&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;SentenceTransformer&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="no"&gt;MAX_TOKENS&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;100&lt;/span&gt;  &lt;span class="c1"&gt;# 이 모델의 128토큰 입력 한도보다 여유를 둠&lt;/span&gt;
&lt;span class="no"&gt;OVERLAP&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;20&lt;/span&gt;

&lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;token_chunks&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;str&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="n"&gt;ids&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;model&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tokenizer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;encode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;add_special_tokens&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="kc"&gt;False&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="n"&gt;step&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="no"&gt;MAX_TOKENS&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="no"&gt;OVERLAP&lt;/span&gt;
    &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;start&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="nb"&gt;range&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nb"&gt;len&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ids&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;step&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="n"&gt;part&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;ids&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;start&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;start&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="no"&gt;MAX_TOKENS&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;part&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
            &lt;span class="n"&gt;decoded&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;model&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tokenizer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;decode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;part&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;skip_special_tokens&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="kc"&gt;True&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;strip&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;decoded&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
                &lt;span class="k"&gt;yield&lt;/span&gt; &lt;span class="n"&gt;decoded&lt;/span&gt;

&lt;span class="n"&gt;chunks&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;meta&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;pdf&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="nc"&gt;Path&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"docs"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;glob&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"*.pdf"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;page_no&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;page&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="nb"&gt;enumerate&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;PdfReader&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;str&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;pdf&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;pages&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="n"&gt;text&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;extract_text&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="ow"&gt;or&lt;/span&gt; &lt;span class="s2"&gt;""&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;strip&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;part&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="nf"&gt;token_chunks&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
            &lt;span class="n"&gt;chunks&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;append&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;part&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="n"&gt;meta&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;append&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="s2"&gt;"file"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;pdf&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"page"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;page_no&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="n"&gt;vectors&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;model&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;encode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;chunks&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;normalize_embeddings&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="kc"&gt;True&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="n"&gt;index&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;faiss&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;IndexFlatIP&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;vectors&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;shape&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="n"&gt;index&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;np&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;asarray&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;vectors&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;dtype&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"float32"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="n"&gt;faiss&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;write_index&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;index&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"documents.faiss"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="nc"&gt;Path&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"metadata.json"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;write_text&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;json&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;dumps&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="s2"&gt;"chunks"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;chunks&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"meta"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;meta&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;ensure_ascii&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="kc"&gt;False&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;encoding&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"utf-8"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;텍스트 추출 결과가 모두 비어 있으면 &lt;code&gt;chunks&lt;/code&gt;도 비어 임베딩·인덱스 생성 단계가 실패할 수 있습니다. 먼저 &lt;code&gt;docs&lt;/code&gt;에 PDF가 있는지와 페이지별 추출 텍스트가 비어 있지 않은지 확인하고, 스캔 문서라면 OCR 결과를 검토한 뒤 다시 진행합니다. 검색 결과가 없을 때도 빈 근거를 답변 근거로 취급하지 않아야 합니다.&lt;/p&gt;

&lt;p&gt;임베딩과 원문 메타데이터는 함께 관리해야 합니다. 이 예제는 &lt;a href="https://huggingface.co/sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2/blob/main/sentence_bert_config.json" rel="noopener noreferrer"&gt;paraphrase-multilingual-MiniLM-L12-v2 모델 설정&lt;/a&gt;에서 공식 문서로 확인한 최대 입력 길이 128토큰을 넘기지 않도록 100토큰 단위와 20토큰 겹침을 사용합니다. 실제 문서에서는 문단·제목·문장 경계도 함께 고려하고, 다른 임베딩 모델을 쓰면 그 모델의 토큰 한도에 맞춰 값을 다시 정해야 합니다. 검색 시 질문도 같은 임베딩 모델로 변환한 뒤, 내적 또는 코사인 유사도(벡터 방향의 가까움)를 계산해 상위 결과를 가져옵니다. 예제에서는 동일한 임베딩 모델로 문서와 질문을 변환하며, 실제 서비스에서는 검색 목적에 맞는 모델을 선택하고 모델이 query/document 전용 인코딩을 지원한다면 해당 방식을 사용하는 것이 좋습니다. &lt;code&gt;IndexFlatIP&lt;/code&gt;는 단순하고 이해하기 쉽지만 문서 수가 많아지면 별도 벡터 데이터베이스를 검토할 수 있습니다.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="n"&gt;question&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"환불 조건은 무엇인가요?"&lt;/span&gt;
&lt;span class="n"&gt;q&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;model&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;encode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;question&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;normalize_embeddings&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="kc"&gt;True&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;astype&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"float32"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="n"&gt;scores&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;ids&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;index&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;search&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;q&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;4&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="n"&gt;context&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"\n\n"&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="s2"&gt;"[{meta[i]['file']} p.{meta[i]['page']}]\n{chunks[i]}"&lt;/span&gt;
    &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;ids&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  로컬 LLM 연결과 선택 기준
&lt;/h2&gt;

&lt;p&gt;검색된 &lt;code&gt;context&lt;/code&gt;와 질문을 프롬프트에 넣어 로컬 LLM API로 전송합니다. 아래 예시의 주소는 OpenAI 호환 API를 제공하는 로컬 서버의 예시이며, 실제 사용하는 서버에 맞게 주소와 모델 지정 방식을 변경해야 합니다. &lt;code&gt;messages&lt;/code&gt;는 대화 메시지 목록, &lt;code&gt;role&lt;/code&gt;은 메시지 발신 유형, &lt;code&gt;content&lt;/code&gt;는 전달할 프롬프트를 뜻하고, &lt;code&gt;model&lt;/code&gt;은 서버에 등록된 모델 이름입니다. 로컬 LLM 자체는 모델 크기, 양자화 방식, 서버 종류를 실행 환경과 요구 사항에 맞춰 선택해야 합니다. 프롬프트에는 “제공된 문서에 근거해 답하고, 근거가 없으면 모른다고 말하라”는 제한을 포함해야 합니다.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;requests&lt;/span&gt;

&lt;span class="n"&gt;prompt&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="s2"&gt;"문서 근거만 사용해 답하세요. 근거가 없으면 모른다고 하세요.\n문서:\n{context}\n질문: {question}"&lt;/span&gt;
&lt;span class="no"&gt;LOCAL_LLM_URL&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"http://127.0.0.1:8000/v1/chat/completions"&lt;/span&gt;
&lt;span class="no"&gt;LOCAL_LLM_MODEL&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"YOUR_SERVER_MODEL_NAME"&lt;/span&gt;  &lt;span class="c1"&gt;# 서버에 실제 등록된 모델명으로 교체&lt;/span&gt;
&lt;span class="n"&gt;response&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;requests&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;post&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="no"&gt;LOCAL_LLM_URL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;json&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="s2"&gt;"model"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="no"&gt;LOCAL_LLM_MODEL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="s2"&gt;"messages"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="s2"&gt;"role"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"user"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"content"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;prompt&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;timeout&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mi"&gt;120&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;print&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;response&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;비교 항목&lt;/th&gt;
&lt;th&gt;단순 파일 검색&lt;/th&gt;
&lt;th&gt;RAG 파이프라인&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;검색 방식&lt;/td&gt;
&lt;td&gt;키워드 일치&lt;/td&gt;
&lt;td&gt;의미 유사도&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;답변 생성&lt;/td&gt;
&lt;td&gt;직접 읽기&lt;/td&gt;
&lt;td&gt;로컬 LLM 연결&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;구축 난이도&lt;/td&gt;
&lt;td&gt;낮음&lt;/td&gt;
&lt;td&gt;중간&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;적합한 문서&lt;/td&gt;
&lt;td&gt;짧고 명확한 문서&lt;/td&gt;
&lt;td&gt;여러 PDF와 자연어 질문&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;정확한 단어를 찾아야 하면 키워드 검색이 유리하고, 표현이 달라도 의미를 찾아야 하면 벡터 검색이 적합합니다. 문서 수가 적으면 파일 기반 저장으로 시작하고, 문서가 늘거나 필터링·권한 관리가 필요하면 벡터 데이터베이스를 선택하세요.&lt;/p&gt;

&lt;h2&gt;
  
  
  자주 묻는 질문
&lt;/h2&gt;

&lt;h3&gt;
  
  
  스캔 PDF도 바로 검색할 수 있나요?
&lt;/h3&gt;

&lt;p&gt;아닙니다. 텍스트 추출 결과가 비어 있으면 OCR로 페이지 이미지를 문자로 변환한 뒤 같은 청킹 과정을 적용해야 합니다. 표와 각주가 많은 문서는 추출 후 원문과 내용이 맞는지 일부 페이지를 확인하세요.&lt;/p&gt;

&lt;h3&gt;
  
  
  RAG를 쓰면 환각이 완전히 사라지나요?
&lt;/h3&gt;

&lt;p&gt;아닙니다. 검색 결과가 틀리거나 관련 청크가 누락되면 로컬 LLM도 잘못 답할 수 있습니다. 답변에 페이지 메타데이터를 표시하고, 중요한 내용은 원문과 대조하는 절차를 두는 것이 좋습니다.&lt;/p&gt;

&lt;h2&gt;
  
  
  결론
&lt;/h2&gt;

&lt;p&gt;PDF RAG는 추출 품질, 청크 설계, 임베딩 일관성, 검색 결과 검증이 핵심입니다. 작은 문서로 파이프라인을 검증한 뒤 규모와 보안 요구에 맞춰 저장소를 확장하세요.&lt;/p&gt;

&lt;h2&gt;
  
  
  관련 글
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://briefold.com/lm-studio-local-llm-gui-guide/" rel="noopener noreferrer"&gt;LM Studio로 로컬 LLM 처음 써보기 (GUI 중심)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://bk-ai-lab.blogspot.com/2026/08/what-is-rag-retrieval-augmented-generation.html" rel="noopener noreferrer"&gt;RAG(Retrieval-Augmented Generation), AI 언어 모델의 지평을 넓히다&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://bk-ai-lab.blogspot.com/2026/08/build-local-llm-ollama-install-model-run.html" rel="noopener noreferrer"&gt;로컬 LLM 구축하기: Ollama 설치부터 모델 실행까지&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;이 글의 원문은 &lt;a href="https://briefold.com/local-llm-pdf-rag-guide/?utm_source=devto&amp;amp;utm_medium=crosspost" rel="noopener noreferrer"&gt;내 PDF 문서를 로컬 LLM에게 검색시키기 — RAG 실전 구축&lt;/a&gt; 에 있습니다. (Originally published on Briefold)&lt;/p&gt;

</description>
      <category>ai</category>
      <category>llm</category>
      <category>automation</category>
    </item>
    <item>
      <title>PostgreSQL 백업과 복구 방법: pg_dump로 데이터 안전하게 관리하기</title>
      <dc:creator>Briefold</dc:creator>
      <pubDate>Fri, 20 Nov 2026 08:52:19 +0000</pubDate>
      <link>https://dev.to/briefold/postgresql-baegeobgwa-boggu-bangbeob-pgdumpro-deiteo-anjeonhage-gwanrihagi-2pbd</link>
      <guid>https://dev.to/briefold/postgresql-baegeobgwa-boggu-bangbeob-pgdumpro-deiteo-anjeonhage-gwanrihagi-2pbd</guid>
      <description>&lt;h2&gt;
  
  
  목차
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;백업 전 준비&lt;/li&gt;
&lt;li&gt;pg_dump로 백업하기&lt;/li&gt;
&lt;li&gt;pg_restore로 복구하기&lt;/li&gt;
&lt;li&gt;실패를 줄이는 점검법&lt;/li&gt;
&lt;li&gt;실제 운영에서 pg_dump를 쓴 사례&lt;/li&gt;
&lt;li&gt;결론&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  백업 전 준비
&lt;/h2&gt;

&lt;p&gt;PostgreSQL 백업은 파일을 만드는 작업과 실제로 복원하는 검증을 함께 진행해야 합니다. 시작하려면 설치된 PostgreSQL과 대상 데이터베이스의 접속 권한을 준비하세요. 명령어는 Linux 또는 macOS 터미널 기준이며, Windows에서는 PostgreSQL의 bin 폴더에서 실행할 수 있습니다. 백업 직후에는 &lt;code&gt;pg_restore --list&lt;/code&gt;로 아카이브를 읽을 수 있는지 확인하고, 별도 데이터베이스에 실제로 복구한 뒤 &lt;code&gt;pg_restore&lt;/code&gt; 실행 결과와 테이블의 필요한 행을 조회하세요. 이 결과가 있어야 백업 파일을 운영 복구에 쓸 수 있는지 판단할 수 있습니다.&lt;/p&gt;

&lt;p&gt;백업 파일을 저장할 디렉터리를 먼저 만들고 접속 정보를 확인하세요. 비밀번호는 명령어에 직접 넣기보다 실행 후 입력하는 방식이 안전합니다. PostgreSQL 컨테이너의 데이터 보존 방법은 &lt;a href="https://briefold.com/postgresql-docker-data-persistent/" rel="noopener noreferrer"&gt;PostgreSQL 데이터 영구 저장&lt;/a&gt;에서도 다룹니다.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;mkdir -p ~/postgres-backups
pg_dump --version
psql -h localhost -U dbuser -d appdb -c &lt;span class="s2"&gt;"SELECT version();"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  pg_dump로 백업하기
&lt;/h2&gt;

&lt;p&gt;운영 데이터베이스를 중단하지 않고 논리 백업(테이블과 데이터를 SQL 명령 형태로 저장하는 방식)을 만들 수 있습니다. 다만 이 "SQL 명령 형태"는 &lt;code&gt;--format=plain&lt;/code&gt;(기본값)으로 저장했을 때의 모습이고, 아래에서 쓸 &lt;code&gt;--format=custom&lt;/code&gt;(사용자 지정 형식)은 같은 논리 백업이라도 사람이 읽을 수 있는 SQL문이 아니라 &lt;code&gt;pg_restore&lt;/code&gt; 전용 바이너리 아카이브로 저장된다는 점이 다릅니다. 복구와 부분 선택이 편리한 사용자 지정 형식으로 저장해 보겠습니다.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;pg_dump -h localhost -U dbuser -d appdb \
  --format=custom \
  --file=&lt;span class="s2"&gt;"$HOME/postgres-backups/appdb.dump"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;백업이 끝나면 파일 존재 여부와 크기를 확인합니다. 백업 파일을 같은 디스크에만 두면 디스크 고장이나 삭제 사고에 함께 영향을 받으므로 NAS나 다른 저장소에도 복사하세요.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;ls -lh ~/postgres-backups/appdb.dump
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  pg_restore로 복구하기
&lt;/h2&gt;

&lt;p&gt;복구 대상 데이터베이스를 비어 있는 상태로 준비한 뒤 &lt;code&gt;pg_restore&lt;/code&gt;를 실행합니다. 대상 데이터베이스가 없다면 먼저 생성하고, 기존 데이터베이스에 덮어쓸 때는 데이터 손실 범위를 확인한 뒤 진행해야 합니다.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;createdb -h localhost -U dbuser restored_appdb
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;본격적으로 복구하기 전에, 아카이브 파일 자체가 정상인지 가볍게 먼저 확인할 수 있습니다. &lt;code&gt;--list&lt;/code&gt; 옵션은 실제로 아무것도 복구하지 않고 아카이브 안에 어떤 테이블·인덱스·시퀀스가 들어있는지 목차만 출력합니다.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;pg_restore --list ~/postgres-backups/appdb.dump
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;이 명령이 오류 없이 목차를 정상 출력하면 아카이브를 읽을 수 있는지에 대한 최소한의 1차 확인이 됩니다. 다만 이건 파일이 읽히는지만 보는 가벼운 1차 점검이며, 데이터가 실제로 제대로 복구되는지는 이어서 실행할 전체 복구로 확인해야 합니다.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;pg_restore -h localhost -U dbuser -d restored_appdb \
  --no-owner \
  ~/postgres-backups/appdb.dump
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;복구 후 테이블과 데이터가 들어왔는지 확인합니다. &lt;code&gt;--no-owner&lt;/code&gt;는 원본 소유자 계정이 복구 서버에 없을 때 권한 오류를 줄이는 옵션이며, 운영 권한 정책에 맞게 적용해야 합니다.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;psql -h localhost -U dbuser -d restored_appdb \
  -c &lt;span class="s2"&gt;"\dt"&lt;/span&gt;
psql -h localhost -U dbuser -d restored_appdb \
  -c &lt;span class="s2"&gt;"SELECT count(*) FROM public.example_table;"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  실패를 줄이는 점검법
&lt;/h2&gt;

&lt;p&gt;복구 대상에 같은 테이블이 이미 있으면 &lt;code&gt;relation already exists&lt;/code&gt; 같은 오류가 나타날 수 있습니다. 이 경우 빈 데이터베이스를 새로 만들거나, 기존 데이터를 지워도 되는 상황에서만 &lt;code&gt;--clean --if-exists&lt;/code&gt; 옵션을 검토하세요.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;pg_restore -h localhost -U dbuser -d restored_appdb \
  --clean --if-exists --no-owner \
  ~/postgres-backups/appdb.dump
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;또 다른 원인은 원본에만 존재하는 사용자와 권한입니다. &lt;code&gt;pg_dump&lt;/code&gt;는 일반적으로 데이터베이스 안의 객체를 저장하지만 서버 전체 역할(role) 정보까지 보존하지는 않으므로, 필요하면 별도로 확인합니다.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;pg_dumpall -h localhost -U dbuser --globals-only \
  &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; ~/postgres-backups/globals.sql
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;pg_dump&lt;/code&gt;는 논리 백업이라 특정 시점으로 즉시 되돌리는 기능이나 서버 전체 장애를 자동으로 막는 기능은 없습니다. 백업 파일을 다른 저장소에 보관하고, 실제 복구 테스트까지 수행해야 백업의 유효성을 확인할 수 있습니다.&lt;/p&gt;

&lt;h2&gt;
  
  
  실제 운영에서 pg_dump를 쓴 사례
&lt;/h2&gt;

&lt;p&gt;이 글에서 설명한 것과 같은 방식의 pg_dump를 실제 운영 중인 서비스에서 사용한 사례가 있습니다. 도메인 전환 작업을 앞두고 관련 테이블 두 개를 일괄 수정하기 전, 되돌릴 수 있는 지점을 남기기 위해 각 테이블을 대상으로 pg_dump를 실행해 압축 백업 파일을 만들었습니다. 이때는 전체 데이터베이스(&lt;code&gt;-d appdb&lt;/code&gt;)가 아니라 &lt;code&gt;-t&lt;/code&gt; 옵션으로 대상 테이블만 지정해 각각 백업했습니다 — 이 사례에서는 수정 대상 테이블만 되돌리면 충분했기 때문입니다. 다만 이 방식은 두 테이블 안의 변경만 되돌릴 수 있을 뿐, 데이터베이스 전체를 대상으로 하는 백업을 대신하지는 않습니다. 백업은 대량 수정 작업 바로 직전에 실행했고, 파일은 이후 계속 보관하고 있습니다. 이 사례는 백업을 만든 시점과 목적을 보여줄 뿐, 이 글의 pg_restore 절차까지 실제로 수행했다는 뜻은 아닙니다 — 수정 작업이 문제없이 끝나 복구가 필요한 상황 자체가 생기지 않았습니다.&lt;/p&gt;

&lt;h2&gt;
  
  
  결론
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;pg_dump&lt;/code&gt;로 백업하고 빈 데이터베이스에 &lt;code&gt;pg_restore&lt;/code&gt;로 복구하면 기본적인 PostgreSQL 데이터 보호 흐름을 만들 수 있습니다. 파일 복사와 복구 테스트를 함께 운영해야 실전 대응력이 생깁니다.&lt;/p&gt;

&lt;h2&gt;
  
  
  관련 글
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://briefold.com/mysql-installation-and-usage-yum/" rel="noopener noreferrer"&gt;MySQL 설치 및 사용법: Yum 저장소와 기본 SQL 시작하기&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://briefold.com/nas-docker/" rel="noopener noreferrer"&gt;NAS Docker 컨테이너 데이터 자동 백업 및 복구 가이드&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://briefold.com/postgresql-docker-data-persistent/" rel="noopener noreferrer"&gt;Docker 재시작 후 PostgreSQL 데이터가 사라지는 이유와 영구 저장 방법&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;이 글의 원문은 &lt;a href="https://briefold.com/postgresql-backup-restore-pgdump/?utm_source=devto&amp;amp;utm_medium=crosspost" rel="noopener noreferrer"&gt;PostgreSQL 백업과 복구 방법: pg_dump로 데이터 안전하게 관리하기&lt;/a&gt; 에 있습니다. (Originally published on Briefold)&lt;/p&gt;

</description>
      <category>devops</category>
      <category>database</category>
    </item>
    <item>
      <title>NAS Docker Permission denied 해결: PUID·PGID와 폴더 권한 확인</title>
      <dc:creator>Briefold</dc:creator>
      <pubDate>Fri, 20 Nov 2026 08:51:08 +0000</pubDate>
      <link>https://dev.to/briefold/nas-docker-permission-denied-haegyeol-puidpgidwa-poldeo-gweonhan-hwagin-10f7</link>
      <guid>https://dev.to/briefold/nas-docker-permission-denied-haegyeol-puidpgidwa-poldeo-gweonhan-hwagin-10f7</guid>
      <description>&lt;p&gt;NAS Docker Permission denied 오류는 폴더 권한 숫자만 바꾼다고 해결되는 문제가 아닙니다. 컨테이너가 실제로 어떤 UID·GID로 파일에 접근하는지, bind mount가 어느 호스트 경로를 가리키는지, NAS가 별도 ACL을 적용하는지를 순서대로 확인해야 합니다.&lt;/p&gt;

&lt;h2&gt;
  
  
  목차
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;먼저 확인할 세 가지&lt;/li&gt;
&lt;li&gt;UID·GID와 마운트 상태 확인&lt;/li&gt;
&lt;li&gt;PUID·PGID를 써야 하는 경우&lt;/li&gt;
&lt;li&gt;PUID·PGID가 없는 이미지의 해결 방법&lt;/li&gt;
&lt;li&gt;NAS ACL과 읽기 전용 설정 확인&lt;/li&gt;
&lt;li&gt;권한을 바꾼 뒤 재확인&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  먼저 확인할 세 가지
&lt;/h2&gt;

&lt;p&gt;확인 관계는 &lt;strong&gt;컨테이너 실행 사용자 → 호스트 마운트 경로 → 소유권·mode와 NAS ACL&lt;/strong&gt;로 이어집니다. 각 지점은 컨테이너 안에서 id 확인, Mounts의 Source·RW 확인, NAS UI와 ls -ldn 확인 순서로 좁힙니다. PUID·PGID의 적용 범위는 아래 이미지 공식 문서로 확인합니다.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;PUID&lt;/code&gt;와 &lt;code&gt;PGID&lt;/code&gt;는 Docker 자체의 표준 환경변수가 아닙니다. &lt;a href="https://docs.linuxserver.io/general/understanding-puid-and-pgid/" rel="noopener noreferrer"&gt;LinuxServer.io의 PUID·PGID 문서&lt;/a&gt;처럼 일부 이미지가 컨테이너 내부 사용자를 호스트 사용자에 맞추기 위해 제공하는 방식입니다. 따라서 이미지 설명에 PUID·PGID 지원이 없다면 임의로 환경변수만 추가해서는 안 됩니다.&lt;/p&gt;

&lt;p&gt;또한 bind mount는 NAS 호스트의 파일이나 디렉터리를 컨테이너에 직접 연결합니다. &lt;a href="https://docs.docker.com/engine/storage/bind-mounts/" rel="noopener noreferrer"&gt;Docker bind mounts 공식 문서&lt;/a&gt;에서 설명하는 것처럼 실제 접근 권한은 호스트 파일시스템과 마운트 설정의 영향을 받습니다.&lt;/p&gt;

&lt;p&gt;Synology, QNAP, UGREEN 등 NAS 제조사마다 ACL 메뉴 위치와 내부 계정 매핑 방식이 다를 수 있습니다. NAS UI에서 보이는 권한 이름과 경로는 해당 제조사의 현재 문서와 함께 확인하세요.&lt;/p&gt;

&lt;h2&gt;
  
  
  UID·GID와 마운트 상태 확인
&lt;/h2&gt;

&lt;p&gt;먼저 컨테이너에서 기본 실행 사용자의 숫자 UID·GID를 확인합니다.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker &lt;span class="nb"&gt;exec&lt;/span&gt; CONTAINER_NAME id
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;이미지가 시작 과정에서 다른 사용자로 권한을 낮추는 구조라면 위 결과만으로 실제 애플리케이션 프로세스 사용자를 단정하면 안 됩니다. 이미지 문서와 컨테이너 내부 프로세스 상태를 함께 확인합니다.&lt;/p&gt;

&lt;p&gt;호스트에서는 실제 마운트 경로와 읽기·쓰기 여부를 확인합니다.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker inspect CONTAINER_NAME
ls -ldn /path/to/nas-folder
stat /path/to/nas-folder
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;docker inspect&lt;/code&gt;의 &lt;code&gt;Mounts&lt;/code&gt;에서 &lt;code&gt;Source&lt;/code&gt;, &lt;code&gt;Destination&lt;/code&gt;, &lt;code&gt;RW&lt;/code&gt;를 확인합니다. &lt;code&gt;ls -ldn&lt;/code&gt;은 사용자 이름 대신 숫자 UID·GID를 보여 주므로 컨테이너에서 확인한 값과 비교하기 쉽습니다. &lt;code&gt;RW&lt;/code&gt;가 &lt;code&gt;false&lt;/code&gt;라면 그 마운트는 읽기 전용입니다.&lt;/p&gt;

&lt;p&gt;호스트 계정의 UID·GID가 필요하면 NAS 셸에서 다음처럼 확인할 수 있습니다.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;id USERNAME
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;여기서 확인해야 할 핵심은 &lt;strong&gt;컨테이너가 쓰는 UID·GID와 호스트 폴더에 쓰기 권한을 가진 UID·GID가 맞는가&lt;/strong&gt;입니다.&lt;/p&gt;

&lt;h2&gt;
  
  
  PUID·PGID를 써야 하는 경우
&lt;/h2&gt;

&lt;p&gt;LinuxServer.io 계열처럼 이미지 문서에서 PUID와 PGID를 지원한다고 명시한 경우에는 호스트 계정의 숫자 UID·GID를 환경변수에 지정할 수 있습니다. 다음은 구조를 보여 주기 위한 예시이며 실제 이미지 이름, 경로, UID·GID는 사용 중인 이미지와 NAS에 맞춰 바꿔야 합니다.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;services&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;app&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;vendor/image:tag&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;PUID&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"1000"&lt;/span&gt;
      &lt;span class="na"&gt;PGID&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"1000"&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;/path/to/nas-folder:/config&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;LinuxServer.io 문서는 자사 이미지에서 PUID·PGID로 내부 사용자를 호스트 사용자에 매핑한다고 설명합니다. 동시에 현재 자사 이미지에는 Docker &lt;code&gt;--user&lt;/code&gt; 대신 PUID·PGID 방식을 사용하도록 안내하고 있으므로, LinuxServer.io 이미지에 &lt;code&gt;user:&lt;/code&gt;를 임의로 섞지 않는 편이 안전합니다.&lt;/p&gt;

&lt;p&gt;PUID·PGID를 변경했다면 컨테이너를 재생성한 뒤 다시 &lt;code&gt;id&lt;/code&gt;, 마운트 상태, 폴더 소유권을 확인합니다. 환경변수만 바뀌고 기존 파일의 소유권이나 NAS ACL이 그대로라면 Permission denied가 계속될 수 있습니다.&lt;/p&gt;

&lt;h2&gt;
  
  
  PUID·PGID가 없는 이미지의 해결 방법
&lt;/h2&gt;

&lt;p&gt;이미지 문서에 PUID·PGID가 없다면 해당 환경변수는 해결책이 아닙니다. 먼저 이미지가 어떤 사용자로 실행되도록 설계됐는지 확인합니다. Docker Compose의 &lt;a href="https://docs.docker.com/reference/compose-file/services/#user" rel="noopener noreferrer"&gt;&lt;code&gt;user&lt;/code&gt;&lt;/a&gt;는 컨테이너 프로세스의 실행 사용자를 덮어쓸 수 있지만, 모든 이미지가 임의 UID·GID 실행을 전제로 만들어진 것은 아닙니다.&lt;/p&gt;

&lt;p&gt;따라서 &lt;code&gt;user: "1000:1000"&lt;/code&gt; 같은 설정은 이미지가 그 실행 방식을 지원할 때만 사용합니다. 진입 스크립트가 root 권한을 필요로 하거나 내부 파일 소유권을 초기화하는 이미지에서는 오히려 시작 실패를 만들 수 있습니다.&lt;/p&gt;

&lt;p&gt;필요하다면 호스트 폴더의 소유자·그룹을 실제 실행 사용자에 맞추되, 공유 폴더 전체에 재귀적으로 &lt;code&gt;chown&lt;/code&gt;하거나 &lt;code&gt;chmod 777&lt;/code&gt;을 적용하는 방식은 피합니다. 기존 서비스와 다른 계정의 접근 권한까지 바뀔 수 있기 때문입니다.&lt;/p&gt;

&lt;h2&gt;
  
  
  NAS ACL과 읽기 전용 설정 확인
&lt;/h2&gt;

&lt;p&gt;Unix 권한이 맞는데도 NAS Docker Permission denied 오류가 남는다면 NAS의 공유 폴더 ACL을 확인합니다. NAS가 별도 ACL을 적용하는 환경에서는 &lt;code&gt;ls -l&lt;/code&gt;의 mode bits만으로 최종 접근 권한을 판단하기 어렵습니다. Docker가 접근하는 사용자나 그룹에 해당 공유 폴더의 쓰기 권한이 있는지 NAS 웹 UI에서도 확인합니다.&lt;/p&gt;

&lt;p&gt;또한 Compose의 bind mount에 &lt;code&gt;:ro&lt;/code&gt;가 붙었는지 확인합니다.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;services&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;app&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;vendor/image:tag&lt;/span&gt;
    &lt;span class="na"&gt;volumes&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;/path/to/nas-folder:/config:ro&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;이 설정은 해당 bind mount를 읽기 전용으로 만듭니다. 쓰기가 필요한 경로라면 이미지 문서를 확인한 뒤 &lt;code&gt;:ro&lt;/code&gt;를 제거하거나 필요한 경로만 별도의 쓰기 가능한 마운트로 분리합니다. 서비스 수준의 &lt;code&gt;read_only: true&lt;/code&gt;와 개별 bind mount의 읽기 전용 옵션은 구분해서 확인해야 합니다.&lt;/p&gt;

&lt;h2&gt;
  
  
  권한을 바꾼 뒤 재확인
&lt;/h2&gt;

&lt;p&gt;수정 후에는 한 번에 여러 설정을 바꾸지 말고 다음 순서로 확인하는 편이 원인을 찾기 쉽습니다.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;code&gt;docker inspect&lt;/code&gt;로 실제 &lt;code&gt;Source&lt;/code&gt;와 &lt;code&gt;RW&lt;/code&gt;를 다시 확인합니다.&lt;/li&gt;
&lt;li&gt;컨테이너의 실행 UID·GID를 다시 확인합니다.&lt;/li&gt;
&lt;li&gt;호스트 폴더의 숫자 소유자·그룹과 쓰기 권한을 비교합니다.&lt;/li&gt;
&lt;li&gt;NAS의 공유 폴더 ACL에서 같은 사용자·그룹의 쓰기 권한을 확인합니다.&lt;/li&gt;
&lt;li&gt;애플리케이션에서 작은 파일 하나를 생성해 Permission denied가 사라졌는지 확인합니다.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;NAS에서 Docker 데이터를 운영할 때의 백업·복구 구조는 &lt;a href="https://briefold.com/nas-docker/" rel="noopener noreferrer"&gt;NAS Docker 컨테이너 데이터 자동 백업 및 복구 가이드&lt;/a&gt;에서 이어서 확인할 수 있습니다.&lt;/p&gt;

&lt;p&gt;핵심은 권한을 넓히는 것이 아니라 &lt;strong&gt;실제로 쓰기를 수행하는 UID·GID, bind mount의 호스트 경로, NAS ACL을 서로 일치시키는 것&lt;/strong&gt;입니다. &lt;code&gt;chmod 777&lt;/code&gt;은 원인을 가리는 임시 조치가 될 수 있으므로 일반적인 해결책으로 사용하지 않는 편이 좋습니다.&lt;/p&gt;




&lt;p&gt;이 글의 원문은 &lt;a href="https://briefold.com/nas-docker-permission-denied-puid-pgid-folder-permission/?utm_source=devto&amp;amp;utm_medium=crosspost" rel="noopener noreferrer"&gt;NAS Docker Permission denied 해결: PUID·PGID와 폴더 권한 확인&lt;/a&gt; 에 있습니다. (Originally published on Briefold)&lt;/p&gt;

</description>
      <category>devops</category>
      <category>docker</category>
      <category>selfhosted</category>
    </item>
  </channel>
</rss>
