Update docs to Plano (#639)

This commit is contained in:
Salman Paracha 2025-12-23 17:14:50 -08:00 committed by GitHub
parent 15fbb6c3af
commit e224cba3e3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
139 changed files with 4407 additions and 24735 deletions

View file

@ -3,17 +3,17 @@
Deployment
==========
This guide shows how to deploy Arch directly using Docker without the archgw CLI, including basic runtime checks for routing and health monitoring.
This guide shows how to deploy Plano directly using Docker without the ``plano`` CLI, including basic runtime checks for routing and health monitoring.
Docker Deployment
-----------------
Below is a minimal, production-ready example showing how to deploy the Arch Docker image directly and run basic runtime checks. Adjust image names, tags, and the ``arch_config.yaml`` path to match your environment.
Below is a minimal, production-ready example showing how to deploy the Plano Docker image directly and run basic runtime checks. Adjust image names, tags, and the ``plano_config.yaml`` path to match your environment.
.. note::
You will need to pass all required environment variables that are referenced in your ``arch_config.yaml`` file.
You will need to pass all required environment variables that are referenced in your ``plano_config.yaml`` file.
For ``arch_config.yaml``, you can use any sample configuration defined earlier in the documentation. For example, you can try the :ref:`LLM Routing <llm_router>` sample config.
For ``plano_config.yaml``, you can use any sample configuration defined earlier in the documentation. For example, you can try the :ref:`LLM Routing <llm_router>` sample config.
Docker Compose Setup
~~~~~~~~~~~~~~~~~~~~
@ -24,14 +24,14 @@ Create a ``docker-compose.yml`` file with the following configuration:
# docker-compose.yml
services:
archgw:
image: katanemo/archgw:0.3.22
container_name: archgw
plano:
image: katanemo/plano:0.4.0
container_name: plano
ports:
- "10000:10000" # ingress (client -> arch)
- "12000:12000" # egress (arch -> upstream/llm proxy)
- "10000:10000" # ingress (client -> plano)
- "12000:12000" # egress (plano -> upstream/llm proxy)
volumes:
- ./arch_config.yaml:/app/arch_config.yaml:ro
- ./plano_config.yaml:/app/plano_config.yaml:ro
environment:
- OPENAI_API_KEY=${OPENAI_API_KEY:?error}
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:?error}
@ -39,7 +39,7 @@ Create a ``docker-compose.yml`` file with the following configuration:
Starting the Stack
~~~~~~~~~~~~~~~~~~
Start the services from the directory containing ``docker-compose.yml`` and ``arch_config.yaml``:
Start the services from the directory containing ``docker-compose.yml`` and ``plano_config.yaml``:
.. code-block:: bash
@ -51,7 +51,7 @@ Check container health and logs:
.. code-block:: bash
docker compose ps
docker compose logs -f archgw
docker compose logs -f plano
Runtime Tests
-------------
@ -65,7 +65,7 @@ Test the chat completion endpoint with automatic routing:
.. code-block:: bash
# Request handled by the gateway. 'model: "none"' lets Arch decide routing
# Request handled by the gateway. 'model: "none"' lets Plano decide routing
curl --header 'Content-Type: application/json' \
--data '{"messages":[{"role":"user","content":"tell me a joke"}], "model":"none"}' \
http://localhost:12000/v1/chat/completions | jq .model
@ -74,7 +74,7 @@ Expected output:
.. code-block:: json
"gpt-4o-2024-08-06"
"gpt-5.2"
Model-Based Routing
~~~~~~~~~~~~~~~~~~~
@ -84,14 +84,14 @@ Test explicit provider and model routing:
.. code-block:: bash
curl -s -H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"Explain quantum computing"}], "model":"anthropic/claude-3-5-sonnet-20241022"}' \
-d '{"messages":[{"role":"user","content":"Explain quantum computing"}], "model":"anthropic/claude-sonnet-4-5"}' \
http://localhost:12000/v1/chat/completions | jq .model
Expected output:
.. code-block:: json
"claude-3-5-sonnet-20241022"
"claude-sonnet-4-5"
Troubleshooting
---------------
@ -100,19 +100,19 @@ Common Issues and Solutions
~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Environment Variables**
Ensure all environment variables (``OPENAI_API_KEY``, ``ANTHROPIC_API_KEY``, etc.) used by ``arch_config.yaml`` are set before starting services.
Ensure all environment variables (``OPENAI_API_KEY``, ``ANTHROPIC_API_KEY``, etc.) used by ``plano_config.yaml`` are set before starting services.
**TLS/Connection Errors**
If you encounter TLS or connection errors to upstream providers:
- Check DNS resolution
- Verify proxy settings
- Confirm correct protocol and port in your ``arch_config`` endpoints
- Confirm correct protocol and port in your ``plano_config`` endpoints
**Verbose Logging**
To enable more detailed logs for debugging:
- Run archgw with a higher component log level
- Run plano with a higher component log level
- See the :ref:`Observability <observability>` guide for logging and monitoring details
- Rebuild the image if required with updated log configuration