🧾 일반 추론 API 가이드

🔹 /general 계열 API를 활용하여 문서 기반 질문-응답 요약을 수행하는 방법을 안내합니다.
🔹 공문 외에 다양한 도메인에 적용 가능하며, 사용자는 URL(Markdwon) 또는 JSON 구조로 답변을 받습니다.

📌 사용 가능한 API 종류

🔹 /general/inner: 내부 모델을 사용하여 일반 요약 수행
🔹 /general/outer: 외부 모델(GPT, Claude, Gemini 등)을 사용하여 요약 수행

✅ 프롬프트 작성 예시

🔹 프롬프트 파일은 반드시 업로드해야 합니다.
🔹 [예시] 질문은 다음과 같이 구성할 수 있습니다:

✅ Schema JSON 작성 예시

🔹 schema_file은 선택사항이며, JSON 형식으로 답변 받기 위해선 작성이 필요합니다.
🔹 추출이 필요한 항목과 항목의 답변을 정의할 때 사용합니다.
🔹 특수 항목은 enum 또는 type 값을 값정할 수 있습니다.

{
    "title": "DocumentSummary",
    "type": "object",
    "properties": {
        "공문번호": { "type": "string" },
        "공문일자": { "type": "string" },
        "수신체": { "type": "string" },
        "수신자": { "type": "string" },
        "수신자_약자": { "type": "string" },
        "발신체": { "type": "string" },
        "발신자": { "type": "string" },
        "발신자_약자": { "type": "string" },
        "공문제목": { "type": "string" },
        "공문제목요약": { "type": "string" },
        "공문내용요약": { "type": "string" },
        "공문간연계": { "type": "string" },
        "공문종류": {
        "type": "string",
        "enum": ["행정/일반", "기술/성과물", "회의/기타"]
        },
        "공문유형": {
        "type": "string",
        "enum": ["보고", "요청", "지시", "회신", "계약"]
        },
        "첨부문서제목": { "type": "string" },
        "첨부문서수": { "type": "integer" }
    },
    "required": [
        "공문번호", "공문일자", "수신체", "수신자", "수신자_약자",
        "발신체", "발신자", "발신자_약자", "공문제목", "공문제목요약",
        "공문내용요약", "공문종류", "공문유형", "첨부문서제목", "첨부문서수"
    ]
}

📌 주요 키·속성 설명

🔹 위 JSON 예시는 Schema 구조를 정의하는 방식으로 작성되어 있으며, 각 키의 의미는 다음과 같습니다:

• title: 스키마의 이름 또는 제목을 정의합니다. 주로 문서나 데이터 객체의 이름을 지정하는 데 사용됩니다.
  [예시]: "title": "DocumentSummary" → 이 JSON은 DocumentSummary라는 이름의 구조입니다.


• type: 이 JSON 구조 자체가 어떤 형태의 데이터인지 정의합니다.
  [예시]: "type": "object" → 이 스키마는 key-value 쌍으로 이루어진 객체(object)입니다.


• properties: 객체 안에 포함된 각 필드(속성)를 정의하는 부분입니다.
  이 안에는 각각의 필드 이름(key)과 해당 값의 type 및 enum 등 상세 정보가 포함됩니다.
  [예시]: "공문번호": { "type": "string" } → 공문번호는 문자열 타입이어야 함을 의미합니다.


• type: 해당 값의 데이터 유형을 지정합니다. 주요 유형은 다음과 같습니다:
  • string: 문자열 (예: "서울특별시")
  • integer: 정수 (예: 3, 25)
  • boolean: 참/거짓 값 (예: true, false)
• enum: 해당 필드가 가질 수 있는 값을 목록으로 제한합니다. 지정된 값 외에는 허용되지 않습니다.
  [예시]: "공문종류": { "type": "string", "enum": ["행정/일반", "기술/성과물", "회의/기타"] }


• required: 필수로 입력되어야 하는 항목들의 리스트입니다.
  이 배열에 나열된 필드가 누락될 경우, JSON이 유효하지 않은 것으로 간주됩니다.
  [예시]: "required": ["공문번호", "공문일자", ...] → 이 필드들은 반드시 포함되어야 합니다.

Tip. schemna json을 사용하는 경우, 프롬프트의 각 항목에 대한 지시문(description)을 각분으로 설정해주면 더 좋습니다.

✅ 사용 절차 안내

🔹 해당 API에 업로드 가능한 파일은 3가지로 구성됩니다:

📌 API 첨부 파일 설명

• input_file: (필수) PDF, 이미지 등 추론 대상 파일을 업로드합니다.
• prompt_file: (필수) 질문이 포함된 질문이 포함된 프롬프트 텍스트(.txt)를 업로드합니다.
• schema_file: (선택) 응답 구조를 정의한 스키마 파일(.json)을 업로드합니다.

1️⃣ Markdown 형식 응답 예시(schema file 미업로드)

🔹 모델은 질문에 대해 줄글 형식의 응답을 생성하며, 응답 JSON에는 다음 필드가 포함됩니다:

📌 주요 답변 키 설명

• generated: 마크다운 형식의 응답 텍스트
• summary_html: 마크다운을 HTML로 변환하여 저장한 URL
🔗 http://172.16.10.176:8888/view/generated_html/Contract_for_Main_Office.html

2️⃣ 구조화 JSON 형식 응답 예시(schema file 업로드)

🔹 /general API에 schema_file을 함께 업로드한 경우, 모델은 지정된 JSON Schema에 따라 항목별 응답을 생성합니다.

📌 주요 답변 키 설명

• generated: JSON 구조의 응답 데이터
• processed: 구조화된 응답이므로 별도의 후처리는 생략되며, 안내 메시지만 포함됩니다.

※ Claude 모델은 영문 필드명만 허용합니다.