DeepDoc Embedding API Integration

What This Integration Does

The DeepDoc Embedding API provides document and code chunk vectorization for the DeepDoc platform. It powers semantic search, retrieval, and chatbot answer generation by converting source content into embeddings. These embeddings are stored in a vector store (typically FAISS) and used for similarity search, reranking, and context expansion. The integration is essential for enabling advanced retrieval workflows, chunking, and artifact citation in DeepDoc-generated documentation and chatbot responses.

Where It Enters the Codebase

The integration is initiated and managed in several key locations:

• Backend Scaffold:
  • scaffold_chatbot_backend() (deepdoc/chatbot/scaffold.py:11) — scaffolds the backend, including embedding config and API key setup.
  • _env_example() (deepdoc/chatbot/scaffold.py:114) — generates .env.example with DEEPDOC_EMBED_API_KEY.
• Configuration:
  • DEFAULT_CHATBOT_CONFIG["embeddings"] (deepdoc/chatbot/settings.py:13) — defines embedding provider, model, API key env, base URL, batch size.
  • chatbot_enabled() (deepdoc/chatbot/settings.py:81) — gates embedding workflows.
  • resolve_service_api_key() (deepdoc/chatbot/settings.py:140) — resolves embedding API key from environment.
• CLI Entrypoints:
  • init() (deepdoc/cli.py:131) — sets up embedding config and API key env during project initialization.
  • generate() (deepdoc/cli.py:246) — triggers embedding workflows as part of documentation generation.
• Config Management:
  • DEFAULT_CONFIG["chatbot"]["embeddings"] (deepdoc/config.py:11) — stores embedding config in .deepdoc.yaml.
  • load_config() (deepdoc/config.py:203) — loads embedding config for downstream use.

Participating Features & Endpoints

The following business features and API endpoints depend on the DeepDoc Embedding API:

• Chatbot Answer Generation
  • Used in the backend scaffold (deepdoc/chatbot/scaffold.py) and runtime service (deepdoc/chatbot/service.py) for semantic retrieval and answer synthesis.
  • See Runtime Services & Chatbot Engine.
• Semantic Search & Retrieval
  • Embeddings power chunk retrieval, reranking, and query expansion.
  • See Documentation Chunking and Summarization.
• Frontend Integration
  • Embedding config is surfaced to the frontend via generated settings and environment variables.
  • See Site Generation & Frontend Integration Overview.
• CLI Workflows
  • deepdoc generate and deepdoc update commands invoke embedding workflows.
  • See CLI Commands & Tooling.

Request/Response or Message Flow

Sequence Diagram

Embedding Workflow

• Request:
  The backend sends a batch embedding request to the DeepDoc Embedding API, including:

  • model: e.g., "azure/text-embedding-3-large"
  • api_key: from DEEPDOC_EMBED_API_KEY
  • batch_size: configurable (default 1 or 24)
  • chunks: list of text/code artifacts

• Response:
  The API returns a JSON payload with embedding vectors for each chunk.

Example Embedding Config (from deepdoc/chatbot/settings.py:13):

"embeddings": {
    "provider": "azure",
    "model": "azure/text-embedding-3-large",
    "api_key_env": "DEEPDOC_EMBED_API_KEY",
    "base_url": "",
    "api_version": "",
    "batch_size": 1,
}

QueryRequest and QueryResponse Schemas (from deepdoc/chatbot/scaffold.py:68):

class QueryRequest(BaseModel):
    question: str
    history: list[dict[str, str]] = Field(default_factory=list)

class QueryResponse(BaseModel):
    answer: str
    code_citations: list[dict[str, Any]]
    artifact_citations: list[dict[str, Any]]
    doc_links: list[dict[str, Any]]
    used_chunks: int

Auth & Configuration

Environment Variables

The DeepDoc Embedding API requires an API key for authentication. This is configured via environment variables and .deepdoc.yaml.

• .env.example is scaffolded with DEEPDOC_EMBED_API_KEY by _env_example() (deepdoc/chatbot/scaffold.py:114).
• Embedding config is stored in .deepdoc.yaml under chatbot.embeddings.

Example .env.example (from deepdoc/chatbot/scaffold.py:114):

DEEPDOC_CHAT_API_KEY=
DEEPDOC_EMBED_API_KEY=

Example .deepdoc.yaml Embedding Section:

chatbot:
  embeddings:
    provider: azure
    model: azure/text-embedding-3-large
    api_key_env: DEEPDOC_EMBED_API_KEY
    base_url: ""
    api_version: ""
    batch_size: 24

Retry, Reconciliation & Failure Handling

Error Handling

• Startup Errors:
  If the embedding API is unavailable or misconfigured, the backend falls back to a FastAPI app with clear error responses:

  • /health: returns {"status": "error", "detail": ...}
  • /query: returns HTTP 503 with {"error": "startup_failed", "detail": ...}
    See _app_py() (deepdoc/chatbot/scaffold.py:30).

• API Key Resolution:
  resolve_service_api_key() (deepdoc/chatbot/settings.py:140) fetches the API key from environment. If missing, embedding requests will fail.

• Batch Size:
  Embedding requests can be batched. If batch size exceeds API limits, requests may fail or be truncated.
  Configurable via batch_size in .deepdoc.yaml.

• Fallback Behavior:
  If embeddings cannot be generated, retrieval and chatbot answers will degrade gracefully, but semantic search will be limited.

Operational Gotchas

• Rate Limits:
  The embedding API may enforce rate limits. Batch requests are recommended for efficiency, but excessive batch sizes can trigger throttling.
• Timeouts:
  Embedding requests may timeout if the API or network is slow. No explicit retry logic is visible in the scaffold; failures are surfaced to the frontend.
• Payload Size:
  Large chunks or batch sizes may exceed API limits. Adjust batch_size in config for optimal throughput.
• Versioning:
  Embedding model and provider are configurable. Ensure compatibility with the API endpoint and model version.
• Monitoring:
  Backend startup errors and embedding failures are surfaced via /health and /query endpoints. Monitor these for operational issues.

Diagrams

Integration Flow

See Also

integration_overview

TODO: This section (integration_overview) needs to be filled in with details from the source files listed above.

embedding_workflows

TODO: This section (embedding_workflows) needs to be filled in with details from the source files listed above.

api_usage

TODO: This section (api_usage) needs to be filled in with details from the source files listed above.

error_handling

TODO: This section (error_handling) needs to be filled in with details from the source files listed above.