Human Approval과 OpenAI-Compatible API를 활용한 n8n 문서 Q&A 워크플로 구축

결정 사항: 승인은 어디에서 이루어져야 할까?

문서 질의응답에서는 AI 모델이 사용된다는 이유만으로 human approval을 추가하지 마세요. 워크플로가 민감한 자료에 접근하거나 검토가 필요한 답변을 게시할 수 있는 지점에 승인을 추가하세요.

실용적인 n8n 설계는 다음과 같습니다.

1. 질문을 받습니다.
2. AI Agent가 문서 검색 요청을 준비하도록 합니다.
3. 코퍼스가 민감하거나, 질의가 제한된 자료를 노출할 수 있거나, 검색에 운영 비용이 드는 경우 검색 도구가 실행되기 전에 사람의 승인을 위해 일시 중지합니다.
4. 출처 메타데이터와 함께 구절을 검색합니다.
5. 모델이 해당 구절만을 근거로 답변하도록 합니다.
6. 출처를 포함한 답변을 반환하거나, 게시 전에 초안을 두 번째 승인 단계로 보냅니다.

이렇게 하면 자주 혼동되는 세 가지 결정을 분리할 수 있습니다. 질문을 허용할지, 검색 작업을 허용할지, 생성된 답변을 전송할 준비가 되었는지가 그것입니다.

n8n은 AI Agent에 연결된 특정 도구에 대한 human review를 문서화합니다. 검토가 활성화되면 워크플로가 일시 중지되고, 검토자는 제안된 도구 호출을 승인하거나 거부할 수 있습니다. 지원되는 동작과 승인 채널에 대한 자세한 내용은 n8n human-in-the-loop documentation을 참조하세요.

사전 요구 사항

다음이 필요합니다.

• AI Agent와 모델 연결이 포함된 n8n 워크플로
• 벡터 스토어, 데이터베이스 또는 내부 검색 서비스와 같은 검색 가능한 문서 소스. 정확한 커넥터는 애플리케이션에 따라 달라지며, 인용된 n8n 페이지에서 정해지는 사항은 아닙니다.
• 문서 메타데이터와 함께 텍스트를 반환하는 검색 도구
• n8n에서 구성된 승인 채널. 문서에는 Chat, Slack, Discord, Telegram, Microsoft Teams, Gmail, WhatsApp Business Cloud, Google Chat 및 Microsoft Outlook을 사용 가능한 채널로 열거합니다.
• OpenAI-compatible API 엔드포인트에 대한 액세스. OneMux는 하나의 OpenAI-compatible API를 통해 주요 AI 모델에 액세스할 수 있도록 제공합니다. 현재 엔드포인트 및 인증 지침은 OneMux quickstart와 API documentation을 사용하세요.

호환성은 조건부입니다. n8n을 연결하기 전에 선택한 엔드포인트가 n8n 노드 또는 HTTP 요청에서 사용하는 요청 형식, 모델 식별자, 인증 방식, 스트리밍 동작, tool calling 및 파라미터를 지원하는지 확인하세요. 이 글은 특정 OneMux 모델 또는 n8n 구성이 테스트되었다고 주장하지 않습니다.

권장 n8n 워크플로 구조

워크플로를 다섯 가지 논리적 단계로 구성하세요.

1. 질문 수집 및 정규화

선택한 n8n 진입점을 사용해 질문을 받고, 사용자 질문, 사용자 또는 워크스페이스 컨텍스트, 선택적 문서 범위 필터가 포함된 작은 객체로 정규화하세요.

제한 없이 입력된 사용자 텍스트를 시스템 지침에 직접 넣지 마세요. 질문은 데이터로 유지하고 에이전트의 동작은 별도로 정의하세요. 워크플로가 테넌트 또는 부서 경계를 지원한다면, 모델이 임의로 만들어내도록 하지 말고 이러한 경계를 제어된 필드로 검색 도구에 전달하세요.

2. 문서 검색 도구 추가

검색 도구를 AI Agent에 연결하세요. 입력은 다음과 같이 범위가 좁고 명확해야 합니다.

{
  "query": "string",
  "document_scope": "string or controlled value",
  "max_results": "integer"
}

검색 결과에는 유용한 인용에 필요한 메타데이터가 충분히 포함되어야 합니다.

{
  "text": "Approved passage from the document",
  "title": "Document title",
  "url": "Document URL or stable identifier",
  "page": "Page number when available",
  "section": "Section heading when available",
  "chunk_id": "Stable passage identifier"
}

위 필드명은 구현 패턴일 뿐, 필수 n8n 스키마에 대한 주장이 아닙니다. 사용하는 커넥터 또는 서비스에 맞게 조정하세요. 중요한 속성은 추적 가능성입니다. 답변 생성기가 구절과 그 출처를 함께 받아야 합니다.

3. 선택한 도구에 human review 적용

AI Agent의 Tools 패널을 열고 Human review 섹션을 찾은 다음, 승인 채널을 선택하고 문서 검색 도구를 해당 검토 단계에 연결하세요. n8n에서 선택한 채널의 인증 정보와 설정을 구성합니다.

검토자에게 보내는 메시지에는 제안된 작업과 파라미터를 표시할 수 있습니다. n8n 문서에서는 이를 위해 $tool.name 및 $tool.parameters 변수를 설명합니다. 실용적인 메시지는 다음과 같습니다.

The AI wants to use {{ $tool.name }} with these parameters:
{{ JSON.stringify($tool.parameters, null, 2) }}

Approve only if the query and document scope are appropriate for this request.

이는 검토자가 다른 팀의 문서를 검색하려는 요청처럼 위험한 범위를 식별할 수 있을 때 가장 유용합니다. 일반적인 공개 문서의 경우 모든 검색에 승인을 요구하면 불필요한 마찰이 생길 수 있습니다. 이런 경우 검색은 자동으로 수행하고, 최종 답변을 게시하거나 전송하는 별도의 도구에 승인을 적용하세요.

4. OpenAI-compatible 모델 엔드포인트 연결

제공업체가 문서화한 엔드포인트와 인증 정보를 사용해 모델 계층을 구성하세요. OneMux를 사용할 때는 OneMux quickstart부터 시작하고, n8n 노드에 필요한 기능을 지원하는 모델을 선택한 뒤 모델 식별자와 요청 파라미터를 확인하세요.

일반적인 요청 형식은 다음과 같을 수 있지만, 이는 테스트된 OneMux 레시피가 아니라 예시입니다.

curl https://api.example-provider.invalid/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {"role": "system", "content": "Answer only from supplied document passages."},
      {"role": "user", "content": "What does the document say about retention?"}
    ]
  }'

플레이스홀더 URL, 키 처리 방식 및 모델 ID는 제공업체의 최신 문서에 나온 값으로 바꾸세요. 워크플로 내보내기 파일이나 사용자가 볼 수 있는 승인 메시지에 인증 정보를 노출하지 마세요. n8n의 모델 노드가 엔드포인트에서 지원하지 않는 파라미터를 요구한다면 호환되는 구성을 사용하세요. 또는 보안 및 응답 파싱 요구 사항을 충족하는 경우에만 HTTP Request 기반 설계를 사용하세요.

5. 답변 프롬프트에서 출처 표시 강제

검색된 구절을 명확히 구분된 컨텍스트로 모델에 제공하고, 실질적인 모든 주장에 인용을 요구하세요. 예를 들면 다음과 같습니다.

You answer questions about the supplied documents.

Rules:
- Use only the passages in DOCUMENT_CONTEXT.
- If the passages do not support an answer, say that the documents do not establish it.
- Do not create titles, URLs, page numbers, or quotations.
- Cite each factual answer using the supplied title and page, section, URL, or chunk ID.
- Distinguish a direct statement from an inference.

DOCUMENT_CONTEXT:
{{ JSON.stringify($json.documents) }}

QUESTION:
{{ $json.question }}

정확한 표현식 문법은 앞선 n8n 노드가 데이터를 구성하는 방식에 따라 달라집니다. 이 프롬프트는 바로 가져와 사용할 수 있는 워크플로 내보내기가 아니라 패턴으로 취급하세요.

승인 설계: 검색과 게시 중 어디에서 승인할까?

승인을 적용할 수 있는 적절한 지점은 두 곳입니다.

고위험 워크플로에서는 두 지점을 모두 사용할 수도 있습니다. n8n 문서에 따르면 검토는 AI Agent에 연결된 모든 도구 또는 선택한 도구에 적용할 수 있으며, 이는 이러한 선택적 설계를 지원합니다. 또한 승인은 주 상호작용과 다른 채널을 통해 이루어질 수 있다고 설명합니다. 예를 들어 사용자 대화는 Slack의 검토자 승인과 연결할 수 있습니다.

시스템 프롬프트 및 거부 동작

어떤 도구에 승인이 필요한지, 거부가 무엇을 의미하는지 에이전트에 알려주세요. 검토자가 검색을 거부하면 에이전트는 표현을 바꿔 동일한 호출을 재시도하거나 근거를 찾았다고 주장해서는 안 됩니다. 요청한 조회가 승인되지 않았음을 설명하고, 가능한 경우 더 좁고 허용된 대안을 제시해야 합니다.

간결한 정책은 다음과 같습니다.

The document_search tool requires human approval. If it is denied, do not call it again for the same request. Tell the user that the lookup was not approved. Never answer from memory when document evidence is required.

이는 에이전트가 거부된 호출을 적절히 처리할 수 있도록 시스템 프롬프트에 도구 및 human-review 동작을 포함하라는 n8n의 문서화된 지침을 따릅니다.

문제 해결 및 제한 사항

승인 요청에 유용한 컨텍스트가 없는 경우

도구 입력이 명시적인 필드를 사용하는지, 검토 메시지에 $tool.name 및 $tool.parameters가 포함되어 있는지 확인하세요. 중요한 범위를 불투명한 문자열 안에 숨기지 마세요.

인용이 누락되는 경우

검색 결과가 모델에 전달되기 전에 확인하세요. 매핑 노드에서 제목, URL, 페이지, 섹션 또는 청크 식별자가 제거되면 모델이 이를 안정적으로 재구성할 수 없습니다. 또한 모델에 근거가 없는 주장을 거부하도록 지시하세요.

엔드포인트가 요청을 거부하는 경우

기본 URL, 인증 헤더, 모델 ID, tool-calling 지원, 컨텍스트 제한 및 파라미터 이름을 확인하세요. OpenAI-compatible이라고 해서 완전히 동일한 것은 아닙니다. n8n의 요청 형식과 제공업체가 문서화한 API를 기준으로 호환성을 확인해야 합니다.

거부 후 응답이 어색해지는 경우

시스템 프롬프트에 명시적인 거부 정책을 추가하고 승인 및 거부 경로를 모두 테스트하세요. n8n은 승인과 취소를 별도의 결과로 문서화하므로, 도구가 항상 실행된다고 가정하지 말고 두 결과를 모두 처리해야 합니다.

워크플로가 너무 느린 경우

위험도가 낮은 모든 검색에 승인하는 대신 선택적 검토를 사용하세요. 민감한 검색 또는 게시에 승인을 유지하고, 자체 환경에서 운영상 영향을 측정하세요. 테스트 없이 모델 속도, 검색 품질 또는 승인 지연을 가정하지 마세요.

비용 및 운영 계획

OneMux는 n8n의 워크플로 제어를 대체하는 수단이 아니라 모델 액세스 경로로서 의미가 있습니다. 모델을 선택하기 전에 최신 OneMux pricing을 검토하고, 입력 및 출력 사용량, 검색량, 반복되는 승인 시도, 문서 검색 서비스 비용을 고려하세요. 적용되는 가격은 선택한 모델과 현재 게시된 약관에 따라 달라지며, 이 글은 특정 요금을 지정하거나 비용 절감을 약속하지 않습니다.

지출 가시성과 모델 선택에 대한 맥락을 확인하려면 OneMux model catalogue를 살펴보세요. 특히 구조화된 출력 또는 tool calling 등 워크플로에 실제로 필요한 기능을 기준으로 모델 선택을 조건부로 결정하세요.

결론

견고한 n8n 문서 Q&A 워크플로는 단순히 에이전트를 모델에 연결한 것이 아닙니다. 승인된 구절을 검색하고, 메타데이터를 보존하며, 적절한 도구 경계에서 검토를 요구하고, 전달받은 근거만 인용하는 답변을 생성하는 통제된 체인입니다.

오케스트레이션과 human approval에는 n8n을 사용하고, 문서화된 엔드포인트와 파라미터가 설계와 일치할 때 OneMux를 실용적인 OpenAI-compatible 모델 액세스 경로로 평가하세요. 작은 코퍼스로 시작해 승인 및 거부 경로를 테스트하고, 근거 없는 주장, 누락된 인용, 호환되지 않는 파라미터를 모델의 미스터리가 아니라 워크플로 실패로 취급하세요.

Sources

• n8n: Human-in-the-loop for tools — 도구 승인 동작, 승인 채널, $tool 표현식 및 거부 처리 지침의 출처입니다.
• OneMux documentation — 현재 API 사용법 및 호환성 세부 정보에 대한 제공업체 문서입니다.
• OneMux quickstart — 엔드포인트 및 인증 구성의 시작점입니다.
• OneMux pricing — 배포 전에 확인할 최신 가격 참고 자료입니다.