dev-corp Pi Settings Guide

이 문서는 host-local Pi coding agent를 dev-corp gemma4:26b provider-pool에 맞춰 설정할 때의 기준이다. 일반 OpenAI-compatible HTTP 직접 호출은 docs/dev-corp-openai-compatible-call-guide.md를 따른다.

대상 범위

Pi package: pi-coding-agent
확인된 Pi version: 0.80.3
Pi binary: pi
설정 디렉터리: ~/.pi/agent
설정 파일:
- ~/.pi/agent/settings.json
- ~/.pi/agent/models.json
대상 provider: dev-corp
대상 model: gemma4:26b
Base URL: http://digitalplatform-iop.cloud:18086/v1

이 가이드는 dev-corp Gemma4 Pi profile 전용이다. dev/Qwen profile, direct provider 실험 profile, IOP Edge/Node/provider/vLLM runtime 설정으로 일반화하지 않는다.

핵심 원칙

Pi 쪽 설정만 바꾼다. IOP Edge config, Node config, provider runtime, vLLM/vLLM-MLX launch option은 건드리지 않는다.
apiKey, authHeader 같은 secret 값은 새로 출력하거나 tracked 문서에 기록하지 않는다.
dev-corp provider가 기본값이어야 하며 direct provider profile을 기본값으로 두지 않는다.
Pi의 openai-completions 경로는 Chat Completions streaming 호출 기준이다. 일반 HTTP stream:false 측정은 Pi가 아니라 표준 caller 가이드에서 다룬다.
dev-corp gemma4:26b는 provider-pool catalog와 provider runtime이 thinking enabled 기준으로 맞춰져 있다. Pi에서 thinking disable을 시도하지 않는다.

settings.json 기준

~/.pi/agent/settings.json의 dev-corp 기준값:

{
  "defaultProvider": "dev-corp",
  "defaultModel": "gemma4:26b",
  "defaultThinkingLevel": "high",
  "hideThinkingBlock": false,
  "httpIdleTimeoutMs": 300000,
  "retry": {
    "provider": {
      "timeoutMs": 300000,
      "maxRetries": 0,
      "maxRetryDelayMs": 60000
    }
  },
  "enabledModels": [
    "dev-corp-direct/**",
    "dev-corp-spark01/**",
    "dev-corp/*"
  ]
}

lastChangelogVersion, theme 같은 Pi UI/local preference field는 기존 값을 보존한다.

models.json 기준

~/.pi/agent/models.json에는 최소한 providers.dev-corp가 아래 의미를 가져야 한다. 예시의 <preserve-existing-secret>은 새 값으로 덮어쓰지 말고 기존 값을 유지한다는 뜻이다.

{
  "providers": {
    "dev-corp": {
      "baseUrl": "http://digitalplatform-iop.cloud:18086/v1",
      "api": "openai-completions",
      "apiKey": "<preserve-existing-secret>",
      "authHeader": "<preserve-existing-secret>",
      "compat": {
        "supportsStore": false,
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false,
        "supportsUsageInStreaming": false,
        "maxTokensField": "max_tokens",
        "requiresToolResultName": true,
        "requiresAssistantAfterToolResult": true,
        "supportsStrictMode": false
      },
      "models": [
        {
          "id": "gemma4:26b",
          "name": "dev-corp gemma4:26b",
          "reasoning": true,
          "input": ["text"],
          "contextWindow": 262144,
          "maxTokens": 32768,
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          }
        }
      ]
    }
  }
}

dev-corp-direct와 dev-corp-spark01 provider가 있더라도 fallback/실험용으로만 둔다. 기본 provider/model은 항상 dev-corp / gemma4:26b다.

Gemma4 한계와 Pi 설정 의미

현재 dev-corp gemma4:26b provider-pool은 Gemma4 agent/tool-call 호환성을 위해 provider runtime을 reasoning_parser=gemma4, tool_call_parser=gemma4, thinking enabled, long-context 기준으로 맞춰 둔 상태다. 이 값들은 provider 쪽 최적화 지점이므로 Pi 설정에서 우회하지 않는다.

주의할 점:

supportsReasoningEffort는 false로 둔다. true로 바꾸면 Pi가 reasoning_effort를 보낼 수 있고, 현재 provider-pool 안정 경로와 어긋날 수 있다.
defaultThinkingLevel은 high로 둔다. 단, dev-corp supportsReasoningEffort=false 기준에서는 Pi가 top-level reasoning_effort=high를 보내는 용도가 아니라 profile alignment와 UI 기준값이다.
hideThinkingBlock은 현재 기준 false다. reasoning이 흘러오는지 관측 가능한 baseline을 유지한다. UI에서 숨김이 필요하더라도 provider thinking disable과 혼동하지 않는다.
thinking_token_budget, think=false, reasoning_effort=none 같은 요청 파라미터를 Pi 설정으로 강제하지 않는다.
Pi가 보는 context window는 262144, max output token 기준은 32768이다. provider runtime과 IOP catalog도 이 범위에 맞춰져 있어야 한다.

Reasoning을 생성하게 두되 사용자에게 노출하지 않는 정책은 Pi UI/rendering 또는 별도 client filtering 문제다. provider/vLLM 설정이나 IOP provider-pool 기본 파라미터를 바꿔 해결하지 않는다.

검증

설정 후 secret을 출력하지 않는 범위에서 아래를 확인한다.

pi --version
jq '{defaultProvider, defaultModel, defaultThinkingLevel, hideThinkingBlock, httpIdleTimeoutMs, retry, enabledModels}' ~/.pi/agent/settings.json
jq '.providers["dev-corp"] | {
  baseUrl,
  api,
  hasApiKey: has("apiKey"),
  hasAuthHeader: has("authHeader"),
  compat,
  models
}' ~/.pi/agent/models.json

기대값:

pi --version은 현재 기준 0.80.3
defaultProvider는 dev-corp
defaultModel은 gemma4:26b
defaultThinkingLevel은 high
providers.dev-corp.baseUrl은 http://digitalplatform-iop.cloud:18086/v1
providers.dev-corp.api는 openai-completions
providers.dev-corp.compat.supportsReasoningEffort는 false
providers.dev-corp.compat.maxTokensField는 max_tokens
providers.dev-corp.models[0].contextWindow는 262144
providers.dev-corp.models[0].maxTokens는 32768

실제 호출 검증은 짧은 prompt로 수행한다. tool-call 검증이 목적이면 일반 chat smoke와 별도로 forced tool call, auto tool call, streaming delta.tool_calls, tool result 후 최종 답변을 확인한다.

Codex/Claude 작업 프롬프트

아래 프롬프트는 Codex나 Claude에게 host-local Pi 설정을 맡길 때 그대로 전달하는 기준이다.

현재 호스트의 Pi coding agent를 dev-corp Gemma4 provider-pool 기준으로 맞춰줘.

범위:
- 수정 가능: ~/.pi/agent/settings.json, ~/.pi/agent/models.json
- 수정 금지: IOP repo 설정, Edge config, Node config, provider runtime, vLLM/vLLM-MLX start script, secret 원문 출력
- 현재 기준 provider/model: dev-corp / gemma4:26b
- Base URL: http://digitalplatform-iop.cloud:18086/v1
- Pi API: openai-completions

작업 규칙:
1. 먼저 pi --version, ~/.pi/agent/settings.json, ~/.pi/agent/models.json 구조를 확인해.
2. apiKey, authHeader, token, secret 값은 화면에 출력하지 말고 기존 값을 보존해.
3. 편집 전 settings.json과 models.json을 timestamp가 붙은 백업 파일로 복사해.
4. settings.json에는 아래 기준을 반영해:
   - defaultProvider: dev-corp
   - defaultModel: gemma4:26b
   - defaultThinkingLevel: high
   - hideThinkingBlock: false
   - httpIdleTimeoutMs: 300000
   - retry.provider.timeoutMs: 300000
   - retry.provider.maxRetries: 0
   - retry.provider.maxRetryDelayMs: 60000
   - enabledModels: ["dev-corp-direct/**", "dev-corp-spark01/**", "dev-corp/*"]
   - theme, lastChangelogVersion 등 기존 UI/local preference는 보존
5. models.json의 providers.dev-corp는 아래 기준을 반영해:
   - baseUrl: http://digitalplatform-iop.cloud:18086/v1
   - api: openai-completions
   - 기존 apiKey/authHeader는 보존
   - compat.supportsStore: false
   - compat.supportsDeveloperRole: false
   - compat.supportsReasoningEffort: false
   - compat.supportsUsageInStreaming: false
   - compat.maxTokensField: max_tokens
   - compat.requiresToolResultName: true
   - compat.requiresAssistantAfterToolResult: true
   - compat.supportsStrictMode: false
   - model id: gemma4:26b
   - model name: dev-corp gemma4:26b
   - reasoning: true
   - input: ["text"]
   - contextWindow: 262144
   - maxTokens: 32768
   - cost input/output/cacheRead/cacheWrite: 0
6. dev-corp-direct 또는 dev-corp-spark01 provider가 있으면 삭제하지 말고 fallback/실험용으로 보존해. 단 defaultProvider/defaultModel은 dev-corp/gemma4:26b로 둬.
7. supportsReasoningEffort를 true로 바꾸거나 think=false, reasoning_effort=none, thinking_token_budget 강제 설정을 추가하지 마. dev-corp Gemma4 provider-pool은 현재 thinking enabled 기준으로 튜닝되어 있고, reasoning hide는 provider 설정 변경이 아니라 client/UI 처리 문제야.
8. 변경 후 jq로 secret 없이 핵심 값만 출력해서 검증해.

검증 출력에는 apiKey/authHeader 원문을 절대 포함하지 말고, hasApiKey/hasAuthHeader boolean 정도만 보여줘.

실패 시 되돌리기

백업한 파일로 settings.json과 models.json을 되돌린 뒤 Pi를 다시 실행한다. 실패가 think=false, reasoning_effort, thinking_token_budget, direct provider URL 변경과 관련되어 보이면 해당 변경을 제거하고 dev-corp public Edge route 기준으로 복원한다.

9.1 KiB Raw Blame History