# dev-corp OpenAI-Compatible Call Guide

dev-corp `gemma4:26b` 모델을 OpenAI-compatible 방식으로 직접 호출할 때 필요한 최소 설정이다.

## 기본값

| 항목 | 값 |
| --- | --- |
| Base URL | `http://digitalplatform.iop.ai.kr:18086/v1` |
| Chat endpoint | `POST /v1/chat/completions` |
| Models endpoint | `GET /v1/models` |
| Model | `gemma4:26b` |
| Auth header | `Authorization: Bearer <token>` |

`/v1/responses`가 아니라 `/v1/chat/completions`를 사용한다.

## 권장 요청

기본 권장 호출은 `stream:true`다. `think`, `reasoning_effort`, `thinking_token_budget`은 보내지 않는다.
반복 출력 loop를 피하려면 최소 sampling parameter로 `temperature: 0.2`, `top_p: 0.95`를 함께 보낸다.

```bash
curl -N http://digitalplatform.iop.ai.kr:18086/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{
    "model": "gemma4:26b",
    "messages": [
      {
        "role": "user",
        "content": "간단히 응답해줘."
      }
    ],
    "temperature": 0.2,
    "top_p": 0.95,
    "stream": true
  }'
```

Streaming을 처리하지 않는 client에서는 선택적으로 `stream:false`를 사용할 수 있다.

```bash
curl -fsS http://digitalplatform.iop.ai.kr:18086/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{"model":"gemma4:26b","messages":[{"role":"user","content":"ok만 응답해줘."}],"temperature":0.2,"top_p":0.95,"stream":false}'
```

## 파라미터

| 파라미터 | 권장 |
| --- | --- |
| `model` | `gemma4:26b` |
| `stream` | 기본 `true`, 필요하면 `false` |
| `temperature` | 최소 기준 `0.2` |
| `top_p` | 최소 기준 `0.95` |
| `think` | 생략 |
| `reasoning_effort` | 생략 |
| `thinking_token_budget` | 생략 |
| `include_reasoning` | 숨김 보장용으로 쓰지 않음 |

## Repetition loop 조정

dev-corp `gemma4:26b` OpenAI-compatible 호출에서는 반복 출력 loop를 피하기 위한 최소 기준으로 `temperature: 0.2`, `top_p: 0.95`를 설정한다. 두 값을 생략해 provider 기본값에 맡기지 않는다.

그래도 repetition loop가 발생하면 한 번에 여러 값을 크게 바꾸지 말고, `temperature`는 조금씩 올리고 `top_p`는 조금씩 낮추는 방향으로 조정한다.

## Reasoning 표시 옵션

응답에 reasoning field가 포함될 수 있다. 표시하지 않는 UX가 필요하면 호출하는 client에서 아래 field를 렌더링 대상에서 제외하는 방식으로 처리할 수 있다.

- non-stream: `choices[].message.reasoning_content`, `choices[].message.reasoning`, `choices[].message.reasoning_text`
- stream: `choices[].delta.reasoning_content`, `choices[].delta.reasoning`, `choices[].delta.reasoning_text`

`include_reasoning=false`만으로 reasoning 표시 여부가 항상 제어된다고 가정하지 않는다.