# 코드 서빙 컨테이너 서비스

## 컨테이너 서비스 사용자 매뉴얼

코드 서빙은 개발자가 작성한 Python 코드를 컨테이너로 배포해 GenOS에서 호출할 수 있도록 만든 단위입니다. 컨테이너 서비스는 이렇게 배포된 코드 서빙을 GenOS 내부의 다른 기능 — 채팅의 워크플로우, 데이터 전처리기, MCP 서버 — 에서 사용 가능한 형태로 노출하는 기능입니다.

즉, 같은 코드 서빙 하나를 토글만 켜면 워크플로우로도, 전처리기로도, MCP 서버로도 동시에 활용할 수 있습니다. 각 용도마다 코드에서 구현해야 하는 HTTP path 규약이 정해져 있어, 컨테이너 서비스 설정 화면에서 path를 지정하고 검증 버튼으로 응답 여부를 즉시 확인합니다.

이번 페이지에서는 코드 서빙을 컨테이너 서비스로 활성화하고 사용하는 전체 절차를 살펴보겠습니다.

***

### 1. 사전 준비

#### a. 코드 서빙 생성 및 배포

컨테이너 서비스는 코드 서빙이 **배포된 상태(Online / Running)** 일 때만 활성화할 수 있습니다. 다음 상태에서만 토글 변경이 가능합니다.

* `PUBLISHED` (배포 완료)
* `WAITING_TO_REPUBLISH` (재배포 대기 — 컨테이너는 살아있는 상태)
* `INITIALIZING` (초기화 중)
* `RUNNING` (실행 중)

미배포 상태에서는 컨테이너 서비스 탭에 안내 메시지가 노출되며 토글이 비활성화됩니다.

<figure><img src="/files/VcAW91btT49CC5Wl2MrO" alt=""><figcaption></figcaption></figure>

#### b. 컨테이너 서비스 탭 진입

코드 서빙 상세 화면에서 **\[컨테이너 서비스]** 탭을 클릭합니다.

상단에는 \[샘플 코드 보기] 버튼이 있으며, 클릭하면 워크플로우 / 전처리기 / MCP 각 타입별 Python 샘플 코드 다이얼로그가 열립니다. main.py에 그대로 복사해 사용할 수 있습니다.

<figure><img src="/files/0TI7Tp1Wb0CUSyufQmB0" alt=""><figcaption></figcaption></figure>

***

### 2. 워크플로우로 사용

채팅 서비스의 워크플로우 드롭다운에 본 코드 서빙을 노출합니다.

#### a. \[워크플로우로 사용] 체크박스 활성화

체크박스를 켜면 호출 경로 입력 필드가 나타납니다.

#### b. 채팅 호출 경로 입력

* **기본값**: `/chat`
* **필수 여부**: 필수
* **코드 구현 요구사항**: 코드 안에 `POST <경로>` 핸들러를 구현해야 합니다. 채팅이 이 경로로 `{question, overrideConfig, history}` 형태의 요청을 보냅니다.

<figure><img src="/files/4KEjlJC4T42peBebgOPX" alt=""><figcaption></figcaption></figure>

#### c. \[검증] 버튼 클릭

입력한 경로로 `{question: "__verify__", overrideConfig: {}, history: []}` probe 요청을 보내 응답 여부를 확인합니다.

* 성공 시: 초록색 알림 "검증 성공 — 엔드포인트가 응답합니다."
* 실패 시: 빨간색 알림에 BE 에러 메시지 표시

#### d. \[저장] 버튼 클릭

화면 하단의 \[저장] 버튼을 누르면 설정이 반영됩니다. 저장 후에는 채팅 서비스의 워크플로우 드롭다운에서 이 코드 서빙이 선택 가능한 옵션으로 노출됩니다.

***

### 3. 전처리기로 사용

데이터 전처리기 목록에 노출되어, 데이터 인덱싱 시 본 코드 서빙을 전처리기로 선택할 수 있게 합니다.

#### a. \[전처리기로 사용] 체크박스 활성화

#### b. 전처리기 호출 경로 입력

* **기본값**: `/preprocess`
* **필수 여부**: 필수
* **코드 구현 요구사항**: 코드 안에 `POST <경로>` 를 구현해 `{file_path, file_content_base64, params}` 를 받고, `{code: 0, data: [VectorProperties...]}` 를 반환해야 합니다.

#### c. 지원 확장자 입력

* **형식**: 쉼표로 구분된 확장자 목록 (예: `hwp, pdf, md, txt, json`)
* **필수 여부**: 필수
* **검증 규칙**: 시스템의 업로드 정책(`uploadPolicy.allowed_extensions`)에 포함된 확장자만 허용됩니다. 허용 목록에 없는 확장자를 입력하면 빨간 테두리와 함께 오류 메시지가 표시됩니다.

데이터 인덱싱 시 사용자가 업로드한 파일의 확장자가 여기 등록된 것과 일치하면, 이 전처리기가 후보로 노출됩니다.

<figure><img src="/files/04DZJEt5J24JGwNZHLQk" alt=""><figcaption></figcaption></figure>

#### d. 기본 파라미터 (JSON) 입력

* **형식**: 유효한 JSON 객체
* **필수 여부**: 선택 (비워두면 BE가 정책 디폴트로 채움)
* **용도**: 데이터 인덱싱 폼에 기본값으로 채워질 파라미터. 예: `{"chunk_size":1000,"chunk_overlap":100}`

JSON 파싱에 실패하면 저장 시점에 "Invalid Default Params JSON" 토스트가 노출되며 저장이 중단됩니다.

#### e. \[검증] 버튼 클릭

입력한 경로로 `{file_path: "__verify__", params: {}}` probe 요청을 보내 응답 여부를 확인합니다.

#### f. \[저장] 버튼 클릭

저장하면 데이터 인덱싱 화면의 전처리기 목록에 본 코드 서빙이 후보로 노출됩니다.

***

### 4. MCP 서버로 사용

본 코드 서빙을 MCP(Model Context Protocol) 서버로 노출합니다. 워크플로우, Flowise, 외부 MCP 클라이언트에서 호출할 수 있습니다.

MCP는 두 개의 path를 사용합니다 — **도구 목록 조회**(tools/list)와 **도구 실행**(tools/call).

#### a. \[MCP 서버로 사용] 체크박스 활성화

#### b. 도구 목록 path (tools/list) 입력

* **기본값**: `/mcp/list`
* **필수 여부**: 필수
* **코드 구현 요구사항**: 코드 안에 `POST <경로>` 를 구현해 다음 형태로 응답해야 합니다.

```json
{
  "tools": [
    {
      "name": "도구이름",
      "description": "도구 설명",
      "inputSchema": { ... }
    },
    ...
  ]
}
```

#### c. 도구 실행 path (tools/call) 입력

* **기본값**: `/mcp/call`
* **필수 여부**: 필수
* **코드 구현 요구사항**: 코드 안에 `POST <경로>` 를 구현해 `{name, arguments}` 를 받고 다음 형태로 응답해야 합니다.

```json
{
  "content": [
    { "type": "text", "text": "..." }
  ]
}
```

#### d. 외부 호출 주소 안내

저장 후 외부 호출 주소가 자동으로 발급됩니다. Flowise 및 외부 MCP 클라이언트는 이 주소를 등록해 본 코드 서빙을 MCP 서버로 사용합니다.

<figure><img src="/files/WXrCeNvyVzlVhhQXW7rm" alt=""><figcaption></figcaption></figure>

#### e. \[저장] 버튼 클릭

***

### 5. 다중 컨테이너 서비스 동시 사용

세 가지 타입은 **상호 배타적이지 않습니다.** 동일한 코드 서빙에서 워크플로우, 전처리기, MCP를 동시에 활성화할 수 있습니다. 각 토글마다 별도의 path를 구현하면 됩니다.

예시:

* `POST /chat` — 워크플로우 호출 처리
* `POST /preprocess` — 전처리기 호출 처리
* `POST /mcp/list`, `POST /mcp/call` — MCP 도구 목록·실행 처리

저장 시 활성화된 토글의 path만 검증되며, 비활성 토글은 기본값으로 초기화됩니다.

<figure><img src="/files/XTZIUruzMvLmm0lp4aVt" alt=""><figcaption></figcaption></figure>

***

### 6. 저장 시 입력 검증

\[저장] 버튼 클릭 시 활성화된 토글의 필수 입력을 검증합니다. 누락된 항목이 있으면 다음과 같이 처리됩니다.

* 첫 번째 오류 메시지가 화면 우측 상단에 토스트로 노출됩니다.
* 활성 토글의 모든 invalid 필드가 동시에 빨간 테두리와 helperText로 시각화됩니다.
* 입력을 정상화하면 빨간 테두리가 자동으로 해제됩니다.

검증되는 항목:

* 워크플로우 토글 ON 시 → 채팅 호출 경로 필수
* 전처리기 토글 ON 시 → 전처리기 호출 경로 필수, 지원 확장자 형식 유효성
* MCP 토글 ON 시 → 도구 목록 path, 도구 실행 path 모두 필수
* 전처리기 기본 파라미터 → JSON 파싱 가능 여부

***

### 7. 활용 확인

저장이 완료되면 코드 서빙으로 사용한 항목이 각 타입의 목록에 자동으로 추가됩니다. 다음 위치의 목록에서 노출 여부를 확인합니다.

* **워크플로우**: 워크플로우 목록에서 본 코드 서빙으로 생성된 워크플로우가 추가되었는지 확인합니다.
* **전처리기**: 전처리기 목록에서 본 코드 서빙으로 생성된 전처리기가 추가되었는지 확인합니다.
* **MCP**: MCP 서버 목록에서 본 코드 서빙으로 생성된 MCP 서버가 추가되었는지 확인합니다.

<figure><img src="/files/AHh5ovmVHgOnWcBb4GsN" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/gpph6TQrG4odJV3a47j8" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/GalJ1hnc0dzbDaAJzFMB" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://genos-docs.gitbook.io/default/v1.8.5/basic-tutorials/guides/development/code_serving/container_service.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.